कैंपेन इंजन

dispatchatlas.lab बेंचमार्क प्रदाताओं व सॉल्वर रजिस्ट्रियों के पार पुनरुत्पाद्य कैंपेन आयोजन का स्वामी है। यह कैंपेन विन्यास सत्यापित करता है, रन लागत आकलित करता है, रनटाइम परिवेश कैप्चर करता है, चेकपॉइंट दृढ़ करता है, विफलताएँ वर्गीकृत करता है, और पूर्ण कार्य दोहराए बिना अपूर्ण रनों को फिर शुरू करता है।

चलाने-योग्य उदाहरण: examples/run_experiment.py एक स्मोक पायलट, एक रुकने-नियम अपश्लेषण, व एक सीड-संवेदनशीलता स्वीप चलाता है; examples/inspect_engine.py होस्ट-सजग worker आकार-निर्धारण व संयोज्य समाप्ति मानदंडों का निरीक्षण करता है।

विन्यास

कैंपेन बेंचमार्क चयनक, सॉल्वर id, उद्देश्य, सीड नीति, रुकने के मानदंड, प्रकटीकरण लेबल, संसाधन बजट, पुनर्प्रयास नीति, निष्पादन मोड, व एक आउटपुट रिपॉज़िटरी घोषित करते हैं।

from dispatchatlas.core import DisclosureLabel, TerminationPolicy
from dispatchatlas.lab import (
    CampaignConfig,
    ExecutionMode,
    OutputPolicy,
    ResourceBudget,
)
 
config = CampaignConfig(
    campaign_id="smoke-campaign",
    benchmark_ids=("dispatchatlas-smoke",),
    solver_ids=("earliest-start", "ndso-core"),
    objectives=("makespan",),
    root_seed=20260527,
    seed_namespace="docs.campaign.smoke",
    stop=TerminationPolicy(max_iterations=5),
    output=OutputPolicy("experiments"),
    resources=ResourceBudget(max_workers=2, max_concurrent_runs=2),
    execution_mode=ExecutionMode.BOUNDED,
    disclosure_labels=(DisclosureLabel.PUBLIC,),
)

OutputPolicy.root_dir प्रयोग कार्यक्षेत्र जड़ है, प्रति-कैंपेन निर्देशिका नहीं: प्रत्येक रन उस जड़ के भीतर results/{campaign}/{solver}/{benchmark}/ के नीचे उतरता है।

सत्यापन चयनित बेंचमार्क समस्याओं व सॉल्वर id को नियतात्मक रन id में विस्तारित करता है। पूर्ण-कैंपेन योजनाएँ लागत आकलनों के लिए dry-run की जा सकती हैं, पर निष्पादन तब तक अवरुद्ध रहता है जब तक सांख्यिकीय डिज़ाइन अनुमोदन दर्ज न हो। सीड किए स्टोकैस्टिक सॉल्वर solver_seed_replicates के माध्यम से स्पष्ट प्रति-सॉल्वर सीड प्रतिकृतियाँ घोषित कर सकते हैं, जबकि नियतात्मक सॉल्वर प्रति समस्या व उद्देश्य एक दर्ज सीड पर रहते हैं।

निष्पादन

CampaignRunner को एक बेंचमार्क प्रदाता, एक सॉल्वर रजिस्ट्री, व FileResultRepository के साथ उपयोग करें। डिफ़ॉल्ट runner बंडल किए स्मोक बेंचमार्क प्रदाता व सॉल्वर रजिस्ट्री को तार से जोड़ता है।

from pathlib import Path
 
from dispatchatlas.lab import default_campaign_runner
 
runner = default_campaign_runner(Path("experiments"))
plan = runner.validate(config)
budget = runner.dry_run(plan)
index = runner.run(plan)

निष्पादन मोड:

मोड	व्यवहार
`sequential`	एक समय में एक नियतात्मक इकाई चलाता है।
`parallel`	अधिकतम `ResourceBudget.max_workers` worker थ्रेड उपयोग करता है।
`bounded-resource`	`max_workers` व `max_concurrent_runs` में से छोटा उपयोग करता है।
`replay`	पूर्ण रनों को दर्ज सीडों से पुनः निष्पादित करता है और सत्यापित करता है कि प्रत्येक पुनर्गणित सामग्री हैश दृढ़ अभिलेख से मेल खाता है; किसी भी विचलन पर विफल-होकर-बंद।

कैंपेन प्रकार व रन-गणना नीति

एक कैंपेन एक kind घोषित करता है। नीचे की कैटलॉग तालिका प्रयोग-डिज़ाइन वर्गिकी से उत्पन्न होती है, अतः इसका कुल पंक्तियों से ही गणनीय है।

Generated from the experiment-design taxonomy: 6 campaign kinds.

Search campaign kinds

Showing 6 of 6 campaign kinds.

Campaign kinds — 6 rows, build-inlined from the public campaign-kind bundle.
Kind	Role
`comparative`	Compares at least two solvers under identical termination, equal computational budgets, and one equal per-algorithm tuning budget.
`ablation`	Isolates one named mechanism per configuration so analysis can attribute that mechanism's contribution.
`sensitivity`	Measures how results respond when one campaign input, such as the stopping policy, varies.
`hyperparameter`	Explores solver hyperparameter settings under a declared tuning budget.
`pilot`	Runs a smaller preparatory design that exercises the full campaign pipeline; the default kind.
`targeted`	Realizes one report-specific experiment design over a deterministic benchmark subset.

रन-गणना नीति pilot व full चरणों में प्रति (स्टोकैस्टिक-सॉल्वर, इंस्टेंस) कोष्ठक कम-से-कम तीस स्वतंत्र रनों का एक सांख्यिकीय-सामर्थ्य तल प्रवर्तित करती है, यादृच्छिकीकृत एल्गोरिद्मों की विश्वसनीय तुलना हेतु आवश्यक नमूना आकारों पर स्थापित मार्गदर्शन का अनुसरण करते हुए (Arcuri & Briand 2014); नियतात्मक सॉल्वर एक बार चलते हैं। एक smoke कैंपेन तल-से-नीचे गणना को अस्वीकार करने के बजाय चिह्नित करता है, अतः त्वरित जाँचें एक सामर्थ्य-अपर्याप्त डिज़ाइन को चुपचाप भेजे बिना सस्ती बनी रहती हैं।

द्वैत रुकने प्रोटोकॉल

एक कैंपेन प्रत्येक स्टोकैस्टिक-सॉल्वर परिणाम को एक स्थिर-बजट प्रोटोकॉल (पुनरावृत्तियाँ या घड़ी-समय) व एक स्थिर-लक्ष्य प्रोटोकॉल (एक लक्ष्य उद्देश्य पर समाप्त) दोनों के अंतर्गत रिपोर्ट करता है। दोनों को stopping_protocols के माध्यम से एक कैंपेन पर घोषित करें; प्रत्येक कोष्ठक एक स्थिर सीड साझा करते हुए प्रत्येक प्रोटोकॉल के अंतर्गत योजित होता है, अतः दो रिपोर्टें सीधे तुलनीय हैं। प्रत्येक पूर्ण रन अपने निदान में stopping_protocol कुंजी के अंतर्गत अपना प्रोटोकॉल दर्ज करता है।

from dispatchatlas.core import TerminationPolicy
from dispatchatlas.lab import StoppingProtocol, StoppingProtocolKind
 
protocols = (
    StoppingProtocol(
        name="fixed-budget",
        kind=StoppingProtocolKind.FIXED_BUDGET,
        stop=TerminationPolicy(max_iterations=200),
    ),
    StoppingProtocol(
        name="fixed-target",
        kind=StoppingProtocolKind.FIXED_TARGET,
        stop=TerminationPolicy(max_iterations=2000, target_objective=100.0),
    ),
)

निष्पक्ष तुलना

एक comparative कैंपेन प्रत्येक सॉल्वर को समान समाप्ति, समान संगणनात्मक बजट, व एक समान प्रति-एल्गोरिद्म TuningBudget के अंतर्गत व्यायाम कराता है, रन क्लिष्ट में प्रति-कोष्ठक स्थिर सीड लॉग करते हुए। सॉल्वरों के पार ट्यूनिंग बजट को समान करना स्थापित बेंचमार्किंग अभ्यास का अनुसरण करता है, जो मानता है कि असमान ट्यूनिंग प्रयास एक अन्यथा निष्पक्ष तुलना को भ्रमित करता है (Bartz-Beielstein et al. 2020)। कैंपेन विफल-होकर-बंद होता है जब तक यह कम-से-कम दो सॉल्वरों की तुलना न करे व एक ट्यूनिंग बजट घोषित न करे; गारंटी योजना मेटाडेटा में fair_comparison* कुंजियों के अंतर्गत दर्ज होती है।

सुरक्षित-अधिकतम-worker टोपोलॉजी

probe_capacity सबसे बड़ी worker गणना चुनता है जो संसाधन बजट के भीतर रहती है, प्रत्येक सटीक सॉल्वर के आंतरिक थ्रेड पूल को सीमित करता है ताकि worker गुणा थ्रेड कभी होस्ट को अति-अभिदान न करे, नेस्टेड पूलों को रोकने हेतु रैखिक-बीजगणित थ्रेड-पूल परिवेश को पिन करता है, और sequential व replay मोड के लिए एक नियतात्मक worker पर वापस गिरता है। प्रत्येक रन का स्वामित्व ठीक एक worker के पास है व अपने स्वयं के run-id-कुंजीबद्ध अभिलेख में दृढ़ होता है, अतः समुच्चयन केवल-विलय है: merge_only_aggregation रनों को id द्वारा क्रमित करता है व उनके सामग्री-हैश स्ट्रिंग हैश करता है, worker पूर्णता क्रम की परवाह किए बिना एक बिट-स्थिर कैंपेन हैश उत्पन्न करते हुए।

कमांड-पंक्ति इंटरफ़ेस

dispatchatlas-lab कमांड एक JSON विन्यास फ़ाइल के रूप में घोषित कैंपेन को सत्यापित, लागत- आकलित, चलाता, फिर शुरू, व पुनः-प्रदर्शित करता है:

dispatchatlas-lab validate --config examples/campaign-config.json
dispatchatlas-lab dry-run --config examples/campaign-config.json
dispatchatlas-lab run --config examples/campaign-config.json
dispatchatlas-lab resume --config examples/campaign-config.json
dispatchatlas-lab replay --config examples/campaign-config.json

चेकपॉइंट व परिणाम

फ़ाइल-समर्थित रिपॉज़िटरी OutputPolicy.root_dir को प्रयोग कार्यक्षेत्र जड़ के रूप में मानता है व पदानुक्रमिक रन-स्तरीय लेआउट लिखता है:

results/{campaign_id}/plan.json व results/{campaign_id}/environment.json
results/{campaign_id}/{solver_id}/{benchmark_id}/run_{idx}.json — प्रति पूर्ण रन एक अभिलेख, जहाँ idx रन योजना से नियत शून्य-आधारित प्रतिकृति सूचकांक है
results/{campaign_id}/{solver_id}/{benchmark_id}/failures/run_{idx}.attempt-{N}.json — प्रति विफल प्रयास एक अभिलेख
.checkpoints/{campaign_id}.json — कैंपेन चेकपॉइंट
logs/{campaign_id}_{timestamp}.log — प्रति-कैंपेन निष्पादन लॉग
ENVIRONMENT.md — निष्पादन परिवेश का कार्यक्षेत्र-स्तरीय Markdown स्नैपशॉट (होस्ट, OS, Python, रिपॉज़िटरी कमिट व शाखा, कैप्चर समय, CPU गणना, मशीन), प्रत्येक कैंपेन आरंभीकरण पर अधिलेखित

प्रत्येक रन अभिलेख अपने नियतात्मक वैज्ञानिक पेलोड पर content-hashed होता है; अभिलेख पर संग्रहीत घड़ी-समय व संसाधन माप उद्गम हैं व हैश के बाहर रहते हैं, अतः replay सत्यापन रन-से-रन समय भिन्नता से अप्रभावित रहता है। चेकपॉइंट पूर्ण, विफल, व लंबित रन id सूचीबद्ध करते हैं, अतः एक बाद का resume() कॉल पूर्ण कार्य छोड़ देता है। समानांतर कैंपेन प्रत्येक worker के समाप्त होते ही पूर्ण परिणाम अभिलेख दृढ़ करते हैं व कैंपेन अंत पर अंतिम चेकपॉइंट लिखते हैं; resume अब भी शेष कार्य योजित करने से पहले डिस्क से पूर्ण अभिलेख खोजता है।

परिवेश कैप्चर

कैंपेन परिवेश मुद्रांक में ऑपरेटिंग सिस्टम, Python संस्करण, प्लेटफ़ॉर्म टैग, पैकेज संस्करण, CPU गणना, मशीन/प्रोसेसर तथ्य, वर्तमान Git कमिट, विन्यास हैश, व सीड नीति शामिल हैं। होस्टनेम, क्रेडेंशियल, व परिवेश चर कैप्चर नहीं किए जाते।

विफलता प्रबंधन

विन्यास, डोमेन, असमर्थित-क्षमता, व अनुपस्थित वैकल्पिक निर्भरता त्रुटियाँ टर्मिनल हैं। अन्य रनटाइम अपवाद पुनर्प्रयास बजट समाप्त होने तक पुनर्प्राप्य हैं। प्रत्येक विफल प्रयास पुनर्प्रयास या पुनरारंभ से पहले दृढ़ होता है।

प्रमाण निर्माता

tools/build_campaign_evidence.py का उपयोग एक दर्ज विन्यास से अभ्यर्थी बेंचमार्क कैटलॉग, पूर्ण तुलनात्मक कैंपेन, NDSO अपश्लेषण, संवेदनशीलता जाँचें, प्रमाण बंडल, व पोर्टल डेटासेट बनाने हेतु करें:

uv run python tools/build_campaign_evidence.py `
  --output-root .\experiments `
  --problem-count-per-profile 30 `
  --stochastic-seeds 10 `
  --campaign-suffix local

निर्माता कैटलॉग मूर्तीकरण, कैंपेन योजना, निष्पादन, विश्लेषण, बंडल निर्यात, व रिपोर्ट लेखन के लिए चरण प्रगति को stderr पर उत्सर्जित करता है। निर्माता जानबूझकर उत्पन्न प्रमाण को Git-ट्रैक स्रोत वृक्षों के बाहर लिखता है। इसके आउटपुटों को केवल रिलीज़ व प्रकटीकरण गेटों के माध्यम से पदोन्नत करें।