محرّك الحملات

يمتلك dispatchatlas.lab تنسيق الحملات القابل للتكرار عبر مزوّدي النسخ المرجعية وسجلّات الحلّالات. يتحقّق من تهيئة الحملة، ويُقدِّر كلفة التشغيل، ويلتقط بيئة زمن التشغيل، ويُديم نقاط التفتيش، ويُصنِّف الإخفاقات، ويستأنف التشغيلات غير المكتملة دون تكرار العمل المكتمل.

أمثلة قابلة للتنفيذ: examples/run_experiment.py يقود طيّارًا دخانيًّا، واستئصال قاعدة-توقّف، ومسح حساسية-بذرة؛ وexamples/inspect_engine.py يفحص تحجيم العمّال الواعي-بالمضيف ومعايير الإنهاء القابلة للتركيب.

التهيئة

تُعلِن الحملات مُحدِّدات النسخ المرجعية، ومعرّفات الحلّالات، والأهداف، وسياسة البذور، ومعايير التوقّف، ووسوم الإفصاح، وميزانيات الموارد، وسياسة إعادة المحاولة، ووضع التنفيذ، ومستودع مخرجات.

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}/ داخل ذلك الجذر.

يُوسِّع التحقّقُ مسائلَ النسخ المرجعية المختارة ومعرّفات الحلّالات إلى معرّفات تشغيل حتمية. ويمكن تشغيل خطط الحملة-الكاملة في dry-run لتقديرات الكلفة، لكن التنفيذ يبقى محظورًا حتى يُسجَّل اعتماد التصميم الإحصائي. ويمكن للحلّالات العشوائية المبذورة أن تُعلِن تكرارات بذرة لكل-حلّال صريحة عبر solver_seed_replicates، بينما تبقى الحلّالات الحتمية على بذرة مُسجَّلة واحدة لكل مسألة وهدف.

التنفيذ

استخدم CampaignRunner مع مزوّد نسخ مرجعية، وسجلّ حلّالات، وFileResultRepository. ويُوصِّل المُشغِّل الافتراضي مزوّد النسخ المرجعية الدخاني المُحزَّم وسجلّ الحلّالات.

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` خيوط عمّال.
`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*.

طوبولوجيا أقصى-عمّال آمنة

يختار probe_capacity أكبر عدد عمّال يبقى داخل ميزانية الموارد، ويَحُدّ تجمّع الخيوط الداخلي لكل حلّال دقيق بحيث لا يُفرِط العمّال ضرب الخيوط في الاشتراك على المضيف أبدًا، ويُثبِّت بيئة تجمّع-خيوط الجبر-الخطي لمنع التجمّعات المتداخلة، ويتراجع إلى عامل حتمي واحد لوضعَي sequential وreplay. ويملك كلَّ تشغيلٍ عاملٌ واحد بالضبط ويُدام إلى سجلّه الخاص المُفهرَس-بمعرّف-التشغيل، فيكون التجميع دمجًا-فقط: يُرتِّب merge_only_aggregation التشغيلات بالمعرّف ويُجزّئ سلاسل تجزئة-المحتوى الخاصة بها، مُنتِجًا تجزئة حملة ثابتة-بتيًّا بصرف النظر عن ترتيب اكتمال العمّال.

واجهة سطر-الأوامر

يتحقّق أمر 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 على-مستوى-مساحة-العمل لبيئة التنفيذ (المضيف، ونظام التشغيل، وPython، وcommit المستودع وفرعه، ووقت الالتقاط، وعدد المعالجات، والآلة)، تُكتَب فوقها عند كل تهيئة حملة

يُجزَّأ كلُّ سجلّ تشغيلٍ محتوًى على حمولته العلمية الحتمية؛ والتوقيت الجداري وقياسات الموارد المخزّنة على السجلّ منشأ وتبقى خارج التجزئة، فلا يتأثّر التحقّق من replay بتباين التوقيت من تشغيل إلى تشغيل. وتَسرُد نقاط التفتيش معرّفات التشغيل المكتملة والفاشلة والمعلّقة، فيتخطّى استدعاءُ resume() اللاحق العملَ المكتمل. وتُديم الحملات المتوازية سجلّات النتائج المكتملة كلما أنهى كل عامل، وتكتب نقطة التفتيش النهائية في نهاية الحملة؛ ويظلّ resume يكتشف السجلّات المكتملة من القرص قبل جدولة العمل المتبقّي.

التقاط البيئة

تتضمّن أختام بيئة الحملة نظام التشغيل، وإصدار Python، ووسم المنصّة، وإصدارات الحزم، وعدد المعالجات، وحقائق الآلة/المعالج، وcommit 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. ولا تُرقِّ مخرجاته إلا عبر بوّابات الإصدار والإفصاح.