> ## 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.

# Parameterized Models

> Combine a model with validated parameter values to create a ready-to-run simulation engine for a specific cell

A **Parameterized Model** is a complete, ready-to-run simulation engine that
combines:

1. A specific **[Model](/build/models)** (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`](/core-concepts/cells),
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.

<Note>
  **Parameterized Models are Immutable**

  Once 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.
</Note>

### 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](#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](/build/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.

<Tip>
  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.
</Tip>

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

* Learn how to [run simulations](/simulate/simulations) with your parameterized model
* Explore [optimization](/optimize/overview) to find optimal parameter values