Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ionworks.com/llms.txt

Use this file to discover all available pages before exploring further.

A Parameterized Model is a complete, ready-to-run simulation engine that combines:
  1. A specific Model (e.g., SPM, DFN) - references a Model from the Models table
  2. A complete and validated set of Parameters for that model
This entire package is then linked to a specific Cell Specification, as the parameters are tuned to that cell’s unique chemistry and design. Think of a Parameterized Model as a fully-parameterized, ready-to-run simulation engine for a particular cell.

​
Models vs Parameterized Models

  • Models: Define how to simulate (the mathematical framework)
  • Parameterized Models: Define what to simulate (the model + specific parameter values)
For example, you might have:
  • One Model called “DFN (Full Cell)” that defines the Doyle-Fuller-Newman model structure
  • Multiple Parameterized Models that use this same Model but with different parameter sets:
    • “NMC Cell with Chen2020 Parameters”
    • “NMC Cell with Custom Parameters”
    • “LFP Cell with OKane2022 Parameters”
All three Parameterized Models reference the same Model, but each has its own unique set of parameters.
Parameterized Models are ImmutableOnce a parameterized model is created and used in a simulation, it cannot be edited. This is a key feature that ensures the reproducibility of your results, as a simulation is permanently linked to the exact parameterized model version that generated it.To make changes to an existing parameterized model, you must clone it. This creates a new version that you can modify, preserving the history and integrity of your previous work.

​
Creating a New Parameterized Model

When creating a parameterized model, you first select a Model (either a system model or one you’ve created), then provide a set of parameters. There are several ways to get started with parameters:
  • From Library: Start with a pre-defined parameter set from a public or internal library, such as those from published academic papers. This is often the best starting point.
  • Clone an existing parameterized model: If you have an existing parameterized model in Ionworks Studio that you want to iterate on, you can clone it. This is the perfect workflow for studying the effect of changing one or two parameters.
  • From a BPX File: Upload a JSON file formatted according to the Battery Parameter eXchange (BPX) standard. This allows you to import parameter sets from other tools or collaborators.
  • From a PyBaMM JSON File: Upload parameters in PyBaMM’s serialized JSON format. This is useful when you have parameters exported from PyBaMM or other tools that use PyBaMM’s parameter format.

​
Configuring Parameters

After selecting your starting point, you can review and edit the parameters.

​
Parameter Types

Parameters in Ionworks Studio are not just simple numbers. They can be defined in several ways to capture complex physical behavior:
  • Value: A single numerical value (e.g., Electrode height [m] = 0.05).
  • Expression: A PyBaMM expression that references other parameters (e.g., 1 - Parameter("porosity")). See Dependent parameter expressions below.
  • Function: A mathematical expression, often dependent on other variables like temperature T (e.g., exp(-2500 / (T - 229))).
  • Interpolant: A lookup table defined by a set of data points (e.g., for Open Circuit Potential vs. Stoichiometry). Learn more about interpolants.
The parameter editor organizes parameters into logical groups (e.g., “Cell”, “Anode”, “Cathode”) to make them easier to navigate.

​
Dependent parameter expressions

Some parameters can be defined as expressions that reference other parameters by name. For example, you might set a parameter to 1 - Parameter("porosity") so it is computed from the porosity parameter. These are called dependent parameters. To use an expression:
  1. Click the change circle icon (⟳) next to the parameter value.
  2. Select Expression from the menu (plus-in-circle icon).
  3. Type your expression in the dedicated expression field. Use Parameter("parameter name") to reference another parameter—for example, 1 - Parameter("Negative electrode porosity").
  4. When you leave the field (blur or press Enter), the expression is validated and converted. If it is valid, the computed value is shown below the expression based on the current parameter set.
The expression field shows a placeholder example (e.g., 1 - Parameter("porosity")) when empty. Referenced parameters are automatically added to the parameter list if they do not already exist, so you can fill in their values in the same group.
Expressions support standard Python operations (e.g., +, -, *, /, **) and functions such as exp, log, sqrt, and tanh. You cannot reference parameters that are defined as functions or interpolants—only scalar values and other expressions. Circular references (e.g., A depends on B, B depends on A) are detected and reported as an error.

​
Parameter Validation

Before you can create a parameterized model, Ionworks Studio runs an automatic Parameter Validation check. This service helps ensure that your parameter set is physically realistic and self-consistent. The validator checks for:
  • Deviations from known reference values.
  • Inconsistencies between related parameters.
Each check has a status:
  • Success: The parameter value is within the expected range.
  • Warning: The parameter value is plausible but deviates significantly from the reference.
  • Error: The parameter value is likely to be physically unrealistic or cause the simulation to fail.
For some warnings and errors, the validator provides an autofix option. This allows you to automatically apply a suggested correction to the parameter, helping you quickly resolve issues and ensure your parameterized model is ready for simulation.

​
Downloading a parameterized model

You can download a parameterized model as a ZIP file for offline use or to share with collaborators. From the parameterized model details page, click the Download button. The downloaded ZIP file contains two JSON files:
  • model.json — the model configuration (e.g., model type and options).
  • parameters.json — all parameter values, including scalar values, interpolants, expression functions, and dependent parameter expressions. Metadata keys such as version and citations are excluded from the export.
The ZIP file is named after the parameterized model (e.g., My_NMC_Cell.zip).

​
Editing parameterized models

Parameterized Models can have their name and description updated, but the model reference and parameters cannot be changed after creation. This ensures reproducibility—simulations are permanently linked to the exact parameterized model version that generated them. To modify a parameterized model’s parameters or model reference, you must clone it. Cloning creates a new parameterized model that you can modify, preserving the history and integrity of your previous work.

​
Next Steps