Execution & Summaries

The Execution datamodel manages the real-time observability of campaigns and the persistent records generated by every trial. While Templates define what should happen, Execution Status tracks what is happening, and Summaries record what did happen.

---

Real-Time Monitoring: ExecutionStatus

ARES emits a real-time stream of status updates during a campaign. This data is structured hierarchically, matching the template architecture.

Status Hierarchy

• CampaignExecutionStatus: Top-level state of the entire research workflow.
• ExperimentExecutionStatus: Current progress of a single trial.
• StepExecutionStatus: Current progress of a step (a group of commands).
• CommandExecutionStatus: The granular status of a single device instruction.

message CommandExecutionStatus {
    string command_id = 1;
    string command_name = 2;
    string device_name = 3;
    ExecutionState state = 4;        // Current state (RUNNING, SUCCEEDED, etc.)
    optional AresValue result = 5;    // Captured output of the command
    optional string status_message = 7; // e.g., "Initializing heater..."
}

The ExecutionState Machine

The ExecutionState enum identifies the precise condition of any executable entity (Campaign, Step, or Command):

State	Description
UNDEFINED	Initial state before processing.
WAITING	Queued, waiting for prerequisites or parallel steps.
RUNNING	Actively executing logic or hardware commands.
SUCCEEDED	Completed successfully without errors.
FAILED	Stopped due to an error (hardware, software, or timeout).
PAUSED	Halted by the user.
AWAITING_USER	Waiting for manual intervention (e.g., "Refill the solvent bottle").
REPLANNING	The Planner is actively calculating the next trial.
ANALYZING	The Analyzer is processing the trial data.
RETRYING	Recovering from a recoverable failure based on retry limits.

---

Historical Records: ExecutionSummary

Once a campaign or experiment finishes, ARES generates a persistent Summary record. These records are used for generating reports, auditing research, and providing history to planners.

CampaignExecutionSummary

This is the root record for an entire run. It aggregates all trials, timestamps, and metadata.

message CampaignExecutionSummary {
    optional string unique_id = 1;
    string campaign_id = 2;
    string campaign_name = 5;
    
    repeated ExperimentExecutionSummary experiment_summaries = 3;
    ExecutionInfo execution_info = 4; // Timestamps & Timezones
    
    ExperimentExecutionSummary startup_execution_summary = 8;
    ExperimentExecutionSummary closeout_execution_summary = 9;
}

ExperimentExecutionSummary

An experiment summary contains the "Scientific Truth" of a trial—what was requested vs. what was measured.

message ExperimentExecutionSummary {
    optional string unique_id = 1;
    string experiment_id = 2;
    repeated StepExecutionSummary step_summaries = 3;
    ExecutionInfo execution_info = 4;
    
    // Core Scientific Data
    ExperimentOverview experiment_overview = 5;
    string result_output_path = 6; // File path to raw data (spectra, images)
}

---

The Scientific Record: ExperimentOverview

The ExperimentOverview is the most important message for data scientists. It links the inputs provided to the resulting scalar reward.

message ExperimentOverview {
    optional string unique_id = 1;
    templates.ExperimentTemplate template = 2; // Original intent
    AresStruct result = 3;                      // Final analyzed scalar(s)
    repeated templates.Parameter parameters = 4; // Final resolved inputs
    AnalysisOverview analysis_overview = 5;      // How the result was calculated
}

ExecutionInfo

Every summary entity (Campaign, Experiment, Step, Command) includes an ExecutionInfo block to track performance and timeline:

message ExecutionInfo {
    google.protobuf.Timestamp time_started = 2;
    google.protobuf.Timestamp time_finished = 3;
    string timezone = 4;
}