---

name: simulink-run-parallel-simulations description: >- Use this skill to run multiple Simulink simulations in parallel with parsim, batchsim, and DesignStudy. TRIGGER when: user asks for parameter sweep, sweeping/varying parameters across simulations, Monte Carlo study, batch simulation, running multiple simulations, parallel simulations, large-scale multiple simulations, any task involving repeated simulations with different parameter values, user mentions having an existing script/function for parameter sweeps, or user wants to migrate from parfor/set_param/for-loop patterns to recommended workflows. license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.1"

Running Multiple Simulations in Parallel

Set up and run parallel simulations with parsim, batchsim, or simulink.multisim.DesignStudy.

When to Use

• Parameter sweeps, Monte Carlo studies, batch simulations (local or cluster)
• parsim (local parallel), batchsim (cluster offload), DesignStudy (large-scale combinations)
• preSimFcn/postSimFcn callbacks for setup or post-processing
• Live visualization as simulations complete (ValueStore pattern)

When NOT to Use

• Single simulation → simulating-simulink-models
• Pass/fail tests → testing-simulink-models
• Model editing → building-simulink-models

Prerequisites

If model inspection cannot resolve them, ask the user to provide: the exact model filename, the parameter name and type (workspace variable, block parameter, or model parameter), and the logged signal name(s) to use for metrics. Do not guess any of these values.

Key Functions

| Function | Purpose | Toolbox | Available From | |---|---|---|---| | Simulink.SimulationInput | Specify per-run parameter overrides and callbacks | Simulink | R2017a | | parsim | Run a SimulationInput array / DesignStudy on a parallel pool | Simulink | R2017a | | batchsim | Offload a campaign to a cluster as a background job | Simulink | R2018b | | simulink.multisim.DesignStudy | Generate multi-parameter combinations (with .Variable / .ModelParameter / .BlockParameter / .ExternalInput / .Exhaustive / .Sequential) | Simulink | R2024a | | parpool | Create a parallel pool sized to the campaign | Parallel Computing Toolbox | R2013b | | parcluster | Query the cluster profile and worker capacity | Parallel Computing Toolbox | R2012a |

Match suggestions to the running release. The "Available From" column is authoritative: before recommending a function, confirm it exists in the release in use (version('-release')) and never propose one introduced later.

Workflow

1. Project setup — Before discovery, cd to the project folder if provided and open the Simulink project (openProject) if a .prj exists. This ensures referenced models and supporting files are on the MATLAB path and will be automatically transferred to parallel workers by parsim.

2. Discovery findings — Read-only inspection (no simulations). Report these as facts (no confirmation needed):

   • Model: list .slx files to resolve the actual filename. Never guess a model name — resolve it from the filesystem. Ensure the model is open or loaded before inspecting it.
   • Sweep parameter(s) + type: workspace variable / block parameter / model parameter (see Discovering Parameter Type).
   • Output metrics + how they are accessed: determine where each metric comes from — this decides the postSimFcn accessor before any code is written (see "Getting Metrics Out"):
     • Logged signals: use ModelLoggingInfo.createFromModel(model) to find the logged set without simulating; check the logging variable name (query the model's SignalLoggingName parameter via model_query_params) — do not assume logsout. Access by name.
     • Root Outports: if the model has no logged signals, top-level Outports are the metric source — captured via SaveOutput/yout. Their yout Dataset elements are typically name-less, so getElement('name')/get('name') will not match — access them by BlockPath or positional index. Enumerate the top-level Outport blocks with model_read (or model_overview).
     • Signal marked loggable but currently off: capture it non-destructively with a DataLoggingOverride (see "Getting Metrics Out") — no model edit. If the signal is not in the model's loggable set, verifySignalAndModelPaths errors; that signal needs a model change (enable logging or add an Outport) — surface it as a consent-required plan point, do not enable it silently. Record which mechanism (and therefore which accessor) each metric uses, so the postSimFcn is authored correctly from the start.
   • How the model's data is provisioned: determine where the model's data comes from and whether it loads with the model — a PreLoadFcn, a bound data dictionary, or model-workspace variables all load when the model does, so they reach each worker automatically. Only data from a step that does not run on load must be established explicitly per worker (see "Getting Data and Dependencies to Workers").
   • Pool capacity: parcluster default profile capacity.
   • Optimization compatibility: inferred FastRestart tunability (from parameter type) and whether Rapid Accelerator is a candidate.

3. Simulation plan — The decisions the user approves. Present as numbered points; end with: "Shall I proceed? To adjust, reference any point (e.g., 'for point 3, use X instead')."

   1. Sweep: values + count (linspace for uniform). For Monte Carlo/uncertainty, ask the sampling method if unspecified and record the seed (client-side — see Reproducibility). For multiple parameters, ask Exhaustive (full grid) vs Sequential (paired).
   2. How to run: execution (parsim vs batchsim) and specification (SimulationInput array vs DesignStudy) per the comparison tables — state the choice, don't default silently.
   3. Output signal(s) for metrics.
   4. Post-processing:
      • If the user described a metric or goal → reduce results by default: postSimFcn keeps only that metric and discards all other signals and full time-series. State this in the plan so they can adjust it (e.g. name extra signals to return, which postSimFcn appends to the SimulationOutput).
      • If no goal was given → estimate the total logged-signal data size (signals × time steps × runs) and ask which signals, if any, they want to keep — full logs from many runs can exhaust memory.
   5. Live visualization (optional): ValueStore + KeyUpdatedFcn if wanted, and what to plot. Ask yes/no explicitly.
   6. Pool size: see "Sizing the pool".
   7. Options: UseFastRestart='on' if tunable; Rapid Accelerator if applicable (see those sections). Don't add other options unless asked.
   8. Worker dependencies: ManageDependencies='on' (the default) auto-transfers detected dependencies; ask the user to let you know if any other files need to be manually attached via AttachedFiles.
   9. Script: propose a .m filename in the model's folder, so the sweep script, its callback files, and the model sit together and are on the path when the script runs. If the script must live elsewhere, addpath the model's folder when loading the model so the model and its callback files stay on the path.

   CRITICAL: Do not run simulations until the user explicitly confirms the plan. Always wait for confirmation — even if a reusable script already exists, even if the request seems straightforward. No exceptions.

4. Write the script — Only after the user confirms. Before writing, read the reference file(s) for every topic the task touches (see "References") and follow the patterns they prescribe. Write a .m script file with the agent's Write tool.

5. Test run, then expand — For large campaigns (N ≥ 500), first run the script on the first 2 SimulationInputs (in(1:2)) over only a few time steps (set a short StopTime for the test) to validate postSimFcn correctness and FastRestart/Rapid Accelerator tunability cheaply — the first sim compiles, the second reveals whether the change is tunable. If it succeeds, restore the full StopTime, expand to all simulations (in(1:N)), and run the campaign with run_matlab_file. For small campaigns (N < 500), skip the test and run all N directly (checking ErrorMessage afterward catches a broken postSimFcn). Do not bake a dry-run/validation-mode/sample-size switch into the deliverable script. Do not use Simulation Manager unless the user asks.

6. Analyze and visualize — Use markers + lines for plots.

7. Always ask for next steps — After the sweep, suggest plotting, finding optimal values, flagging outliers, checking requirements, or refining the sweep. Only suggest analysis derivable from the available data — do not offer what was discarded during post-processing.

Discovering Signal Names and Parameter Type

Resolve logged signal names and locate the sweep parameter before writing any code — see references/signal-and-parameter-discovery.md.

---

Choosing How to Run

Two independent choices — pick one from each axis. Both parsim and batchsim accept either a SimulationInput array or a DesignStudy, and both run on a local pool or a remote cluster (MATLAB Parallel Server), so the axes compose freely.

Execution: parsim vs batchsim

| | parsim | batchsim | |---|---|---| | How it runs | Interactive — runs on the pool and blocks the client session | Offloaded — submits a background job (simjob = batchsim(in)) | | Results | Returned in-session: out = parsim(in) | Retrieved later: fetchOutputs(simjob) | | Prefer when | You want results now; short/medium campaigns; iterating on the setup | Long campaigns (hours/days); you want to keep using or close MATLAB; access the job later from another machine | | Simulation Manager UI | Supported (ShowSimulationManager="on") | Not available | | Limitation | Ties up the session until all runs finish | Job-management overhead; results are not immediate |

Specification: SimulationInput array vs DesignStudy

| | SimulationInput array | simulink.multisim.DesignStudy | |---|---|---| | How you define it | Build and index the array explicitly (in(k) = ...) | Declare parameters + a combination (Exhaustive/Sequential); it generates the run set | | Prefer when | Single-parameter sweeps; full per-run control; custom per-run logic | Multi-parameter combinations; large structured sweeps | | Pros | Simple, transparent; straightforward preSimFcn/postSimFcn wiring | No manual nested loops; scales to large grids; OutputLocation control for large result sets | | Limitation | Manual nested loops get unwieldy for multi-parameter grids | More API surface; parsim(designStudy) returns a Future — call fetchOutputs; verify syntax with help simulink.multisim.DesignStudy |

Decide both axes during discovery and record them in the Simulation plan — do not default to parsim + SimulationInput without considering the cues above.

SimulationInput array + parsim

model = 'MyModel';
gains = linspace(0.5, 5, 20);
N = numel(gains);

clear in;  % Prevent stale array from prior runs
in(1:N) = Simulink.SimulationInput(model);   % allocate the array once
for k = 1:N
    % Mutate in(k) in place — do not call Simulink.SimulationInput(model) again here.
    in(k) = in(k).setVariable('Kp', gains(k));  % only the run-to-run override
end

out = parsim(in);

Setup once, vary per run. Build campaign-wide state once — allocate the SimulationInput array, load base data (see "Getting data and dependencies to workers"), open the project. Inside the loop do only what changes run-to-run: per-run overrides and callbacks. Never re-allocate the array or re-run initialization inside the loop.

Sizing the pool

Open a pool of `min(numSims