Create Protocol Simulation

Create a protocol-based simulation.

This endpoint is for creating simulations using the Universal Cycler Protocol format. It requires a model (cycler config dict, regular model dict, or model ID) and a protocol experiment.

For template-based simulations, use POST /simulations/with-template.

Parameters

user_org_client : Tuple[str, str, Client] Current user_id, organization_id, and client usage_service : UsageService Usage tracking service experiment_service : ExperimentService Experiment service for business logic parameterized_models_repository : ParameterizedModelsRepository Parameterized models repository experiment_template_repository : ExperimentTemplateRepository Experiment template repository service_experiment_template_repository : ExperimentTemplateRepository Service experiment template repository study_mapping_repository : StudySimulationMappingRepository Study-simulation mapping repository body : ProtocolSimulationRequest Protocol-based simulation request with model (cycler config or regular) and protocol_experiment activity_log_service : ActivityLogService Activity logging service

Returns

SimulationCreationResponse Simulation creation details including ID, job info, and status

Raises

HTTPException If validation fails, model/experiment creation fails, usage limit reached, or job submission fails

Create Protocol Simulation

cURL

curl --request POST \
  --url https://api.ionworks.com/simulations/protocol \
  --header 'Content-Type: application/json' \
  --data '
{
  "parameterized_model": {},
  "protocol_experiment": {
    "protocol": "<string>",
    "name": "<string>",
    "additional_content_files": {},
    "parameters_schema": {}
  },
  "experiment_parameters": {},
  "design_parameters": {},
  "max_backward_jumps": 123,
  "study_id": "<string>",
  "extra_variables": [
    "<string>"
  ]
}
'

202

{
  "simulation_id": "<string>",
  "job_id": "<string>"
}

Body

application/json

Request body for protocol-based simulation creation.

Strict interface for protocol-based simulations only. The parameterized_model field can be:

• A dict with "quick_model" key containing simplified model config (e.g., {"quick_model": {"capacity": 1.0, "chemistry": "NMC/Graphite"}})
• A regular parameterized model dict (with model, parameters)
• A parameterized model ID string

parameterized_model · Parameterized Model · object string · required

protocol_experiment · ProtocolExperimentConfig · object · required

Experiment configuration using protocol string or Protocol object.

Show child attributes

experiment_parameters · Experiment Parameters · object

design_parameters · Design Parameters · object

Show child attributes

max_backward_jumps · integer | null

study_id · string | null

extra_variables · string[] | null

Response

202

application/json

Successful Response

Response for simulation creation requests.

simulation_id · string · required

job_id · string · required