डोमेन अनुबंध

dispatchatlas.core भीतरी पैकेज सीमा है। यह अपरिवर्तनीय और केवल मानक-पुस्तकालय के ऑब्जेक्ट उपयोग करता है ताकि बेंचमार्क, सॉल्वर, प्रयोग, विश्लेषण और दस्तावेज़ एक साझा शेड्यूलिंग शब्दावली का उपभोग करें।

🗂️ शेड्यूलिंग मॉडल

समस्याएँ ProblemSpec, TaskSpec, ResourceSpec, Dependency, Objective और Constraint से निरूपित होती हैं। उम्मीदवार शेड्यूल Assignment, Schedule, ObjectiveValue और ScheduleResult का उपयोग करते हैं।

मान्यता स्पष्ट है:

from dispatchatlas.core import (
    Duration,
    Objective,
    ObjectiveSense,
    ProblemId,
    ProblemSpec,
    ResourceAmount,
    ResourceId,
    ResourceRequirement,
    ResourceSpec,
    TaskId,
    TaskSpec,
    validate_problem,
)
 
cpu = ResourceId("cpu")
 
problem = ProblemSpec(
    id=ProblemId("smoke"),
    tasks=(
        TaskSpec(
            TaskId("task-a"),
            Duration(1.0),
            demands=(ResourceRequirement(cpu, ResourceAmount(1.0)),),
        ),
    ),
    resources=(ResourceSpec(cpu, ResourceAmount(1.0)),),
    objectives=(Objective("makespan", ObjectiveSense.MINIMIZE),),
)
 
validated = validate_problem(problem)

validate_problem एक मान्यता-मुहर और मशीन-पठनीय रिपोर्ट के साथ एक ValidatedProblem लौटाता है। validate_schedule कार्य कवरेज, संसाधन क्षमता, समय-सीमाओं और निर्भरताओं की जाँच करता है।

🔗 बहु-संसाधन सह-आवंटन

एक कार्य एक साथ एक से अधिक संसाधन की माँग कर सकता है। TaskSpec.demands ResourceRequirement का एक टपल है, और शेड्यूल निर्माता कार्य को उसके द्वारा माँगे गए प्रत्येक संसाधन पर सह-आवंटित करता है, उन्हें कार्य की पूरी अवधि तक एक साथ रखते हुए। इसलिए एक उम्मीदवार शेड्यूल प्रत्येक नियोजन को Assignment.resource_ids के रूप में दर्ज करता है — एक टपल, न कि एकल संसाधन — और validate_schedule पुष्टि करता है कि समय में अतिव्यापी दो कार्य कभी किसी संसाधन को साझा नहीं करते।

संसाधन-संघर्ष ग्राफ शेड्यूलिंग का लीवर है: जिन दो कार्यों के माँग-समुच्चय प्रतिच्छेद करते हैं उन्हें क्रमबद्ध होना चाहिए, जबकि जिनके समुच्चय असंयुक्त हैं वे समवर्ती चलते हैं।

from dispatchatlas.core import ResourceAmount, ResourceId, ResourceRequirement
 
# A task that co-allocates a compute node and an accelerator simultaneously.
demands = (
    ResourceRequirement(ResourceId("edge-0"), ResourceAmount(1.0)),
    ResourceRequirement(ResourceId("gpu-1"), ResourceAmount(1.0)),
)

accelerator-coscheduling, distributed-transaction और fpga-partitioning सातत्य परिवार इस लीवर का प्रयोग करते हैं — पहला एक स्थिर गणना-धन-त्वरक धारण के साथ, दूसरा डेटा शार्ड्स पर परिवर्तनशील-गणनांक लॉक समुच्चय के साथ। चलाने-योग्य examples/inspect_coallocation.py दोनों को शेड्यूल करता है और असंयुक्त-संसाधन कार्यों को समानांतर चलते हुए दिखाता है, जबकि संसाधन-साझा करने वाले कार्य क्रमबद्ध होते हैं।

🧩 ढलनशील निष्पादन

एक कार्य कई मोडों में से किसी एक में चल सकता है। TaskSpec.modes TaskMode का एक टपल है — प्रत्येक एक (demands, duration) युग्म, जहाँ एक व्यापक मोड (अधिक संसाधन माँगने वाला) कम समय में चलता है, ढलनशील गति-वृद्धि। जब modes निर्धारित होता है तब कार्य ढलनशील होता है: शेड्यूल निर्माता, कौन-से संसाधन मुक्त हैं इसके अनुसार, प्रति कार्य वह मोड चुनता है जो सबसे जल्दी समाप्त होता है, अतः शेड्यूल क्रम तय करता है कि प्रत्येक कार्य कितनी समानांतरता का दावा करता है। एक दृढ़ कार्य modes को अनिर्धारित छोड़ता है (डिफ़ॉल्ट) और उसके शीर्ष-स्तरीय duration और demands उसका एकल मोड हैं, जिसे सटीक बैकएंड एक रूढ़िवादी संदर्भ के रूप में शेड्यूल करता है। validate_schedule पुष्टि करता है कि प्रत्येक नियोजन एक घोषित मोड से मेल खाता है, और ढलनशील तथा अपरिशुद्ध (mandatory_duration) निष्पादन परस्पर अनन्य हैं — एक कार्य अपनी समानांतरता चुनता है या वैकल्पिक कार्य त्यागता है, दोनों नहीं।

from dispatchatlas.core import (
    Duration,
    ResourceAmount,
    ResourceId,
    ResourceRequirement,
    TaskMode,
)
 
# Two ways to run one job: wide-and-fast on two workers, or narrow-and-slow on one.
modes = (
    TaskMode(
        demands=(
            ResourceRequirement(ResourceId("worker-0"), ResourceAmount(1.0)),
            ResourceRequirement(ResourceId("worker-1"), ResourceAmount(1.0)),
        ),
        duration=Duration(1.0),
    ),
    TaskMode(
        demands=(ResourceRequirement(ResourceId("worker-0"), ResourceAmount(1.0)),),
        duration=Duration(1.8),
    ),
)

elastic-serverless-autoscale सातत्य परिवार इस लीवर का प्रयोग करता है: प्रत्येक फ़ंक्शन आह्वान एक छोटे साझा बर्स्ट पूल से लिए गए एक, दो या चार वर्कर तक स्केल कर सकता है, अतः शेड्यूल क्रम तय करता है कि कौन-से आह्वान दुर्लभ चौड़े-और-तेज़ मोडों का दावा करते हैं और कौन-से संकीर्ण चलते हैं — विलंबता बनाम संसाधन-लागत का एक समझौता।

🛰️ गैंग सह-शेड्यूलिंग

TaskSpec.gang_id साझा करने वाले कार्य एक गैंग बनाते हैं जिसके वर्कर सभी को भिन्न संसाधनों पर एक ही समय आरंभ होना चाहिए — एक सब-या-कुछ-नहीं सह-आरंभ, जैसे एक समकालिक वितरित-प्रशिक्षण या MPI कार्य को अपने वर्करों के साथ-साथ चलने की आवश्यकता होती है। क्रमिक निर्माता एक पूरे गैंग को उस सबसे पहले क्षण पर परमाणुवत् रखता है जब प्रत्येक वर्कर के संसाधन मुक्त हों, भले ही कोई वर्कर अकेले पहले आरंभ हो सकता था; validate_schedule उस गैंग को अस्वीकार करता है जिसके वर्कर सह-आरंभ नहीं होते (schedule.feasibility.gang_cosched)। एक गैंग वर्कर दृढ़ है (ढलनशील नहीं), क्योंकि गैंग एक स्थिर चौड़ाई पर सह-आरंभ होता है; एक स्वतंत्र कार्य gang_id को अनिर्धारित छोड़ता है।

from dispatchatlas.core import (
    Duration,
    ResourceAmount,
    ResourceId,
    ResourceRequirement,
    TaskId,
    TaskSpec,
)
 
# Two workers of one training job that must launch together on distinct accelerators.
gang = "train-job-0"
workers = tuple(
    TaskSpec(
        id=TaskId(f"worker-{index}"),
        duration=Duration(2.0),
        demands=(ResourceRequirement(ResourceId(f"acc-{index}"), ResourceAmount(1.0)),),
        gang_id=gang,
    )
    for index in range(2)
)

distributed-training-gang सातत्य परिवार इस लीवर का प्रयोग करता है: दो से चार वर्करों के गैंग एक साझा त्वरक पूल का पुनः उपयोग करते हैं और कार्य समय के साथ आते हैं, अतः कोई कार्य तब तक आरंभ नहीं हो सकता जब तक पर्याप्त त्वरक एक साथ मुक्त न हों और शेड्यूल क्रम तय करता है कि कौन-सा कार्य पहले अपना पूर्ण वर्कर समुच्चय प्राप्त करता है।

⚖️ बहु-किरायेदार न्यायसंगत बँटवारा

कार्य एक वैकल्पिक TaskSpec.tenant_id धारण करते हैं जो स्वामी किरायेदार को बहु-किरायेदार न्यायसंगत-बँटवारे के लेखांकन के लिए चिह्नित करता है। dominant-resource-share उद्देश्य (ObjectiveKind.DOMINANT_RESOURCE_SHARE, Ghodsi इत्यादि की प्रभावी संसाधन न्यायपूर्णता के अनुसार) यह अंक देता है कि किरायेदारों के प्रभावी हिस्से कितने समान रूप से संतुलित हैं: प्रत्येक किरायेदार का प्रभावी हिस्सा, संसाधनों भर में, किसी संसाधन की कुल क्षमता-समय का वह सबसे बड़ा अंश है जिसे उसके कार्य अधिग्रहीत करते हैं, और उद्देश्य सबसे अधिक- और सबसे कम-सेवित किरायेदार के बीच का प्रसार है — समान-प्रभावी-हिस्सा (न्यायसंगत) शेड्यूल के लिए 0.0, और जब कोई किरायेदार अपने प्रभावी संसाधन पर एकाधिकार करता है तब अधिक। उद्देश्य न्यूनीकरण-भाव वाला है और बिना-किरायेदार वाले इंस्टेंस पर DEFERRED लौटाता है। tenant_id गैंग, ढलनशील और अपरिशुद्ध निष्पादन के लिए लंबकोणीय है — एक किरायेदार के कार्य इनमें से कोई भी हो सकते हैं; बिना-किरायेदार कार्य tenant_id को अनिर्धारित छोड़ता है।

लीवर नियोजन है, शेड्यूल क्रम नहीं: एक किरायेदार का कुल संसाधन अधिग्रहण उसके कार्यभार से नियत होता है, अतः उसके कार्य किन संसाधनों पर उतरते हैं यही प्रभावी हिस्सों को संतुलित या विषम करता है। चलाने-योग्य examples/multi_tenant_fairshare_study.py एक तीन-नोड पूल पर एक भारी और एक हल्के किरायेदार के न्यायसंगत (प्रसारित) बनाम एकाधिकारी नियोजन को अंक देता है, लीवर को स्पष्ट बनाते हुए।

⏱️ कठोर और मृदु समय-सीमाएँ

एक कार्य एक पूर्णता TaskSpec.deadline धारण कर सकता है, और TaskSpec.deadline_kind वर्गीकृत करता है कि एक चूक का न्याय कैसे होता है। डिफ़ॉल्ट ConstraintKind.HARD एक चूकी समय-सीमा को व्यवहार्यता उल्लंघन बना देता है: validate_schedule एक अवरोधक schedule.feasibility.deadline समस्या उठाता है और शेड्यूल अव्यवहार्य रिपोर्ट होता है। ConstraintKind.SOFT उसी चूक को केवल एक विलंब दंड बना देता है — शेड्यूल व्यवहार्य रहता है जबकि अधिकता lateness उद्देश्य (ObjectiveKind.LATENESS) में संचित होती है, अतः एक मृदु-वास्तविक-समय कार्य को विलंब के लिए दंडित किया जाता है बिना शेड्यूल को अव्यवहार्य बनाए। deadline अनिर्धारित होने पर यह प्रकार निष्प्रभावी है।

समय-सीमा के दो पाठ स्वतंत्र हैं: एक कठोर समय-सीमा व्यवहार्य क्षेत्र को परिबद्ध करती है जबकि एक मृदु समय-सीमा उद्देश्य-सतह को आकार देती है, और एक कार्य किसी का भी उपयोग कर सकता है। चलाने-योग्य examples/infeasibility_study.py कठोर-समय-सीमा मामले को आद्योपांत चलता है — एक अति-प्रतिबंधित इंस्टेंस अव्यवहार्य रिपोर्ट, और जब कोई व्यवहार्य शेड्यूल अस्तित्व में नहीं तब न्यूनतम-अव्यवहार्य क्रम।

💰 लागत मॉडल

लागत-सचेत शेड्यूलिंग एक CostModel से वर्णित होती है, एक पृथक अपरिवर्तनीय कलाकृति, जो अपने पहचानकर्ता द्वारा किसी समस्या से जुड़ी होती है। लागत परत को ProblemSpec के बाहर रखना एक समस्या और उसके लागत-डेटा को स्वतंत्र रूप से संस्करण और क्रमबद्ध करने देता है। एक लागत मॉडल पाँच वैकल्पिक अनुबंध बाँधता है:

• ExecutionTimeMatrix — R||Cmax परिवार के लिए असंबंधित-मशीन प्रसंस्करण समय (p_ij)। मैट्रिक्स विरल है: एक अनुपस्थित (task, machine) युग्म का अर्थ है कि कार्य वहाँ नहीं चल सकता, और इसे पूछताछ करना शून्य पर डिफ़ॉल्ट करने के बजाय त्रुटि उठाता है।
• CompatibilityMask — एक स्पष्ट कार्य-से-मशीन पात्रता समुच्चय, निष्पादन मैट्रिक्स से पृथक रखा गया ताकि पात्रता और सारणीबद्ध समय भिन्न हो सकें।
• SetupMatrix — एक मशीन पर कार्य-से-कार्य या प्रकार-से-प्रकार संक्रमण द्वारा कुंजीबद्ध अनुक्रम-निर्भर सेटअप समय।
• LoadModel — एक भार-निर्भर निष्पादन वक्र जो कड़ाई से बढ़ते विभंजन-बिंदुओं के बीच खंडशः-रैखिक या सोपान अंतर्वेशन के माध्यम से एक भार-स्तर को एक अवधि-गुणक से मानचित्रित करता है।
• CommunicationModel — एक विरल ग्राफ पर अंतर-संसाधन संचार दंड; समान-मशीन संचार निःशुल्क है और असूचीबद्ध अंतर-मशीन युग्म एक घोषित डिफ़ॉल्ट दंड पर वापस आते हैं।

from dispatchatlas.core import (
    CostModel,
    ProblemId,
    ResourceId,
    TaskId,
    execution_matrix_from_iterable,
)
 
cost_model = CostModel(
    problem_id=ProblemId("smoke"),
    execution_matrix=execution_matrix_from_iterable(
        [(TaskId("task-a"), ResourceId("cpu"), 1.0)]
    ),
)

🎯 उद्देश्य और न्यूनीकरण

उद्देश्य परिवार OBJECTIVE_FAMILY में नामित है, जो प्रत्येक उद्देश्य के लिए प्रामाणिक भाव और इकाई दर्ज करता है: makespan, ऊर्जा, लागत, कार्बन, विलंबता, विलंब, न्यायपूर्णता, प्रभावी संसाधन हिस्सा (सबसे अधिक- और सबसे कम-सेवित किरायेदार के प्रभावी संसाधन हिस्से के बीच का प्रसार — बहु-किरायेदार न्यायसंगत बँटवारा), विश्वसनीयता, सुरक्षा, सुदृढ़ता, सेटअप, अपरिशुद्ध पुरस्कार (आंशिक रूप से निष्पादनीय कार्यों के अनिवार्य भाग से परे पूर्ण की गई वैकल्पिक गणना), और भारित समिश्र। एक मापा गया परिणाम VectorObjectiveValue द्वारा वहन होता है, जो एक या अधिक ObjectiveValue प्रविष्टियाँ (नाम से क्रमित) धारण करता है, साथ ही एक स्पष्ट ObjectiveReduction और एक प्रकटीकरण लेबल। भारित-योग और Chebyshev न्यूनीकरण सदिश को अदिशीकृत करते हैं; अ-अदिशीकारी न्यूनीकरण (NONE, LEXICOGRAPHIC) scalarize() पर त्रुटि उठाते हैं ताकि कॉल करने वाले क्रमण को स्पष्ट रूप से संभालें।

✅ व्यवहार्यता रिपोर्ट

build_feasibility_report एक शेड्यूल मान्यता रिपोर्ट को समीक्षक-दृश्य FeasibilityReport में बदल देता है: कठोर उल्लंघन प्रति-पंक्ति InfeasibleRow अभिलेख बन जाते हैं, और नामित उल्लंघित मृदु अवरोध भारित SoftConstraintPenalty प्रविष्टियाँ संचित करते हैं। एक मृदु उल्लंघन कभी feasible को False में नहीं पलटता।

📐 उद्देश्य मूल्यांकन, अवरोध और सीमांत

उद्देश्य-और-अवरोध परत प्रत्येक नामित उद्देश्य की अलग-अलग गणना करती है, अतः कोई भी एक सामान्य बंडल में नहीं मोड़ा जाता। evaluate_objective makespan, विलंब, भार न्यायपूर्णता (Jain का सूचकांक), और — किरायेदार-चिह्नित इंस्टेंसों के लिए — प्रभावी-संसाधन-हिस्सा न्यायपूर्णता को सीधे एक शेड्यूल से व्युत्पन्न करता है, लागत को संलग्न निष्पादन-समय मैट्रिक्स से और अनुक्रम-निर्भर सेटअप समय को संलग्न सेटअप मैट्रिक्स से व्युत्पन्न करता है, और परिकलित घटकों को एक भारित समिश्र में न्यूनीकृत करता है। ऐसे उद्देश्य जिन्हें कोर द्वारा न वहन किए गए मॉडल की आवश्यकता है (ऊर्जा, कार्बन, विलंबता, विश्वसनीयता, सुरक्षा, सुदृढ़ता) एक गढ़े गए मूल्य के बजाय DEFERRED स्थिति और एक नामित तर्काधार के साथ एक ObjectiveEvaluation लौटाते हैं। MultiObjectiveOutcome अदिश मानों, सदिश उद्देश्य और व्यवहार्यता रिपोर्ट को एक नियतात्मक क्रमबद्धन राउंड-ट्रिप के माध्यम से वहन करता है।

अवरोध लेखांकन नामित सेवा-स्तर (SLA) अवरोध को एक प्रथम-श्रेणी अवरोध के रूप में जोड़ता है, दोनों एक कठोर-भंग पथ (एक अव्यवहार्यता) और एक मृदु-दंड पथ (भंग के समानुपाती एक भारित दंड) के साथ। एक ConstraintViolationSummary कठोर उल्लंघन, मृदु दंड, SLA परिणाम और मरम्मत निदान को समुच्चित करता है; यह कठोर नियम उल्लंघन या कठोर SLA भंग में से किसी पर अव्यवहार्य रिपोर्ट करता है।

Pareto सहायक अप्रभुत्व अग्रांत को निकालते हैं और Riquelme, Von Lücken & Barán (2015) के अनुसार चयनित चार नामित गुणवत्ता सूचकांक रिपोर्ट करते हैं: हाइपरवॉल्यूम (प्राथमिक सूचकांक), IGD+ (एक दुर्बल-Pareto-अनुरूप अभिसरण सूचकांक), योगात्मक एप्सिलॉन-सूचकांक, और प्रसार (विविधता सूचकांक)। प्रत्येक सूचकांक अलग-अलग परिकलनीय है। frontier_data विश्लेषण और पोर्टल रेंडरिंग के लिए एक अप्रभुत्व ध्वज के साथ सीमांत-तैयार अभिलेख बनाता है।

सुदृढ़ता को एक मुद्रा-लेबल के बजाय एक मापनीय उद्देश्य के रूप में परिमाणित किया जाता है: evaluate_robustness एक स्पष्ट रूप से घोषित विक्षोभ समुच्चय पर एक उद्देश्य के मान को समुच्चित करता है, या तो सबसे-बुरे-मामले के मान के रूप में या सबसे बुरी पूँछ के सशर्त मूल्य-पर-जोखिम (CVaR) के रूप में। विक्षोभ समुच्चय और समुच्चयन दोनों परिणाम पर दर्ज होते हैं।

⚠️ सीमाएँ

कोर कर्नेल लागत, उद्देश्य और अवरोध के अनुबंध तथा उन्हें मूल्यांकित करने वाली उद्देश्य-और-अवरोध परत परिभाषित करता है; यह अनुकूलन नहीं करता। ऐसे उद्देश्य जिन्हें कोर द्वारा न वहन किए गए मॉडल की आवश्यकता है (ऊर्जा, कार्बन, विलंबता, विश्वसनीयता, सुरक्षा और सुदृढ़ता) आकलित होने के बजाय एक नामित तर्काधार के साथ स्थगित रिपोर्ट किए जाते हैं। LoadModel केवल अपने स्वयं के घोषित वक्र का मूल्यांकन करता है, और ObjectiveDefinition एक मूल्यांकक के बजाय मेटाडेटा वहन करता है।

🌱 उद्गम और बीज

उत्पन्न कलाकृतियाँ Provenance, ArtifactHash, SourceReference, EnvironmentStamp और वैकल्पिक SeedLineage अभिलेख वहन करती हैं। बीज धाराएँ स्थिर निर्देशांकों से व्युत्पन्न होती हैं:

from dispatchatlas.core import derive_seed
 
seed = derive_seed(42, "benchmark.smoke", 0)

समान मूल बीज, नामस्थान और सूचकांक सदैव समान व्युत्पन्न बीज उत्पन्न करते हैं।

📦 क्रमबद्धन

कोर ऑब्जेक्ट प्रामाणिक JSON-संगत मानचित्रणों और ArtifactEnvelope आवरणों के माध्यम से क्रमबद्ध होते हैं। आवरण पेलोड को सामग्री हैश से बाँधते हैं और उस हैश को उद्गम में वापस प्रतिलिपि करते हैं।

🔌 प्रोटोकॉल

बाहरी पैकेज कोर-परिभाषित प्रोटोकॉल पर निर्भर हैं:

• BenchmarkProvider
• Solver
• ExperimentRunner
• ResultRepository
• DisclosurePolicy
• AnalysisExporter

ये प्रोटोकॉल पैकेज आयातों को भीतर की ओर निर्देशित रखते हैं और साथ ही ठोस बेंचमार्क, सॉल्वर, प्रयोग और विश्लेषण पैकेजों को बाद में संयोजित होने देते हैं।