​

UCP Simulation Backend for Design Optimization

​

Problem

​

Solution

​

Architecture

​

UCPSimulation Adapter

class UCPSimulation:
    """Simulation adapter using UCP's native protocol runner.

    Provides the same .solve(inputs=...) interface as iwp.Simulation but runs the
    protocol through UCP's step-by-step engine, which supports dynamic loops,
    conditionals, input parameter expressions, and aggressive model caching.

    Returns ucp_solution.timeseries_solution — a real pybamm.Solution built from
    internal state vectors — so all existing metrics work unchanged.
    """

    def __init__(self, model, parameter_values, protocol_yaml, solver=None, **kwargs):
        # Parse UCP protocol from YAML string
        # Build simulation environment once (model discretization, caching)
        self._sim_env = build_protocol_simulation(
            protocol=protocol_yaml,
            model=model,
            parameter_values=parameter_values,
            **kwargs,
        )

    def solve(self, inputs=None, initial_soc=None, save_at_cycles=None, **kwargs):
        # Run protocol step-by-step through UCP engine
        ucp_solution = run_protocol_simulation(self._sim_env, inputs=inputs)
        # Build pybamm.Solution with cycle structure from UCP step metadata
        return self._build_solution_with_cycles(ucp_solution)

​

Cycle Structure on the Returned Solution

def _build_solution_with_cycles(self, ucp_solution):
    pybamm_sol = ucp_solution.timeseries_solution

    # Group timeseries step indices by cycle_count
    cycle_groups = {}  # cycle_count -> [step_indices]
    step_idx = 0
    for step_sol in ucp_solution.steps:
        if not step_sol.is_timeseries:
            continue
        cycle_groups.setdefault(step_sol.cycle_count, []).append(step_idx)
        step_idx += 1

    # Build a pybamm.Solution per cycle from subsets of the flat arrays
    cycles = []
    for cycle_count in sorted(cycle_groups):
        indices = cycle_groups[cycle_count]
        cycle_sol = pybamm.Solution(
            all_ts=[pybamm_sol.all_ts[i] for i in indices],
            all_ys=[pybamm_sol.all_ys[i] for i in indices],
            all_yps=[pybamm_sol.all_yps[i] for i in indices],
            all_models=[pybamm_sol.all_models[i] for i in indices],
            all_inputs=[pybamm_sol.all_inputs[i] for i in indices],
            termination="final time",
        )
        cycles.append(cycle_sol)

    pybamm_sol.cycles = cycles
    return pybamm_sol

• sol.cycles[c] — real pybamm.Solution with full interpolation
• sol.cycles[c].sub_solutions — steps within that cycle
• save_at_cycles — works as expected
• CycleSlicer, IterativeMetric — work unchanged

• initial_soc: UCP protocols encode initial state in their global config (initial_state_type / initial_state_value). When using the UCP backend, parse_objectives() must NOT extract initial SOC from the experiment config and inject it into parameters (which it currently does at lines 145-160). Otherwise initial SOC is applied twice — once by parse_objectives into parameter_values and again by run_protocol_simulation from the protocol’s global_variables. The fix: skip the initial-state extraction in parse_objectives() when backend="ucp", letting UCP handle it exclusively from the protocol YAML.
• build_protocol_simulation is called once in build(). run_protocol_simulation is called on every optimizer iteration in _run(). UCP’s FastPybammSimulation caches step-specific built models across iterations.
• Solver kwargs: build_protocol_simulation accepts **kwargs that are passed to the solver. _set_up_ucp_simulation should extract solver-related kwargs from simulation_kwargs (e.g., tolerances) and forward them, matching the existing behavior of set_up_simulation in BaseObjective.

​

Known Limitation: UCP-Computed Columns

​

Backend Selection in DesignObjective

def build(self, parameter_values):
    # ... existing variable processing (unchanged) ...

    backend = self.options.get("backend") or os.environ.get(
        "IONWORKS_SIMULATION_BACKEND", "pybamm"
    )

    if backend == "ucp":
        self.simulation = self._set_up_ucp_simulation(model, parameter_values)
    else:
        self.simulation = self.set_up_simulation(model, parameter_values)

​

Config Passthrough

1. API request: Add optional backend field to the optimization request (or use env var only — no API change needed for MVP).
2. Backend converter (design_optimization_converter.py): If a backend field is present in the request, include "backend": "ucp" in each objective’s options dict.
3. parse_objectives(): Passes options through to DesignObjective.__init__() — no changes needed since options is dict[str, Any].
4. DesignObjective.build(): Reads self.options["backend"] as described above.

​

EIS Validation

const hasEisSteps = (experiment: string) => /\beis\b/i.test(experiment);

for (const obj of objectives) {
    if (hasEisSteps(obj.experiment)) {
        toast.error('EIS steps are not supported in design optimization');
        return;
    }
}

import re

def _validate_no_eis_steps(experiment_yaml: str) -> None:
    if re.search(r"\beis\b", experiment_yaml, re.IGNORECASE):
        raise BadRequestError(
            "EIS steps are not supported in design optimization experiments"
        )

​

What Changes

​

What Doesn’t Change

• DesignObjective._run() — unchanged, calls self.simulation.solve(inputs=...)
• All metrics and actions — unchanged, receive pybamm.Solution
• DataFitJobProcessor — unchanged
• DataFit optimizer loop — unchanged
• Frontend form structure — unchanged (just one validation added)

​

Testing

1. Unit: UCPSimulation.solve() — returns valid pybamm.Solution with expected variables, .sub_solutions, and .cycles
2. Unit: cycle structure — .cycles correctly groups steps by StepSolution.cycle_count; each cycle has its own .sub_solutions; save_at_cycles works
3. Unit: EIS validation — frontend regex and backend check both reject protocols with EIS steps, accept protocols without
4. Unit: backend selection — DesignObjective.build() creates UCPSimulation when backend="ucp", iwp.Simulation when backend="pybamm"
5. Unit: env var fallback — IONWORKS_SIMULATION_BACKEND=ucp selects UCP when no explicit option is set
6. Unit: _validate_solution_steps disabled — confirm it is set to False for UCP backend and does not interfere with simulation results
7. Unit: to_config() round-trip — serialize and deserialize a UCP-backed objective, verify backend field and raw experiment YAML survive
8. Unit: initial SOC not double-applied — verify parse_objectives() skips initial state extraction when backend="ucp"
9. Integration: end-to-end optimization — run a design optimization with backend="ucp" and verify it produces equivalent results to backend="pybamm"
10. Regression — existing backend="pybamm" path works identically

​

Risks and Mitigations

• timeseries_solution fidelity: The pybamm.Solution built from UCP state vectors should be equivalent to one from pybamm.Simulation.solve(). This is already tested in the UCP package. Integration tests will verify metric values match between backends.
• Experiment string preservation: Addressed by checking backend="ucp" in parse_options() to skip parse_experiment(). Small, contained change.
• Initial SOC double application: Addressed by skipping initial-state extraction in parse_objectives() when backend="ucp". UCP handles it from the protocol YAML.
• Cycle structure: UCPSimulation.solve() builds .cycles by grouping sub-solutions using StepSolution.cycle_count. Each cycle is a real pybamm.Solution with full interpolation. save_at_cycles, CycleSlicer, and IterativeMetric all work.
• UCP-computed columns: Charge capacity [A.h] and Charge energy [W.h] (UCP DataFrame columns) are not available via timeseries_solution. PyBaMM’s own Discharge capacity [A.h] and Discharge energy [W.h] state variables are available and are what ionworkspipeline metrics use.
• _validate_solution_steps incompatibility: Disabled for UCP backend. UCP’s own protocol validation is sufficient.
• Converter uses HTTPException: The existing design_optimization_converter.py raises HTTPException directly, violating the project’s layered architecture rules. The new EIS validation uses BadRequestError correctly. Cleaning up existing HTTPException usage is out of scope but noted as tech debt.