electrolyte-transport

name

electrolyte-transport

description

Build concentration-dependent electrolyte transport parameters (conductivity, diffusivity, cation transference number) from a material property dataset and feed them to a pipeline DirectEntry. Use when the user wants concentration-dependent electrolyte properties in a fit or simulation, fit a Landesfeind diffusivity curve to electrolyte data, or convert an electrolyte transport dataset into pybamm parameters. Triggers: "electrolyte conductivity", "electrolyte diffusivity", "transference number", "concentration-dependent", "Landesfeind", "electrolyte transport".

Electrolyte Transport from a Material Dataset

Turn a tabular electrolyte transport dataset (property versus electrolyte concentration) stored in the Ionworks material database into a pybamm.ParameterValues of concentration-dependent functions, ready to drop into a pipeline DirectEntry.

When to use

• A current-driven / rate fit needs concentration-dependent electrolyte transport instead of a single constant value.
• You have an "Electrolyte transport properties" dataset (conductivity, diffusivity, cation transference number vs. concentration) in the material DB.
• High-rate DFN solves crash (IDA_ERR_FAIL) because a tabulated interpolant extrapolates to an unphysical (negative / zero) transport value when the electrolyte depletes — switch that property to a fitted closed form.

Prerequisites

1. API key: Settings → API Keys. Set IONWORKS_API_KEY or pass to Ionworks(api_key="...").
2. Dataset ID: the material property dataset UUID. Find it via client.material_property_dataset.list(material_id=...).
3. Run the discover-api skill to explore available endpoints.

Quick start

from ionworks import Ionworks
import ionworks_schema as iws

client = Ionworks()

# Build concentration-dependent electrolyte parameters from the dataset.
params = client.electrolyte.transport_from_dataset("dataset-uuid")

# Drop straight into a DirectEntry — no manual to_json needed.
entry = iws.direct_entries.DirectEntry(parameters=params)

transport_from_dataset returns a pybamm.ParameterValues mapping each pybamm parameter name to a concentration-dependent function (c_e, T). When you pass a ParameterValues to DirectEntry, it serialises the callables into the symbol-JSON the server reconstructs as functions that rebind to the model's own c_e.

Choosing a representation per property

Each property can be either tabulated or fitted to its Landesfeind & Gasteiger (2019) functional form, via forms (keyed by pybamm parameter name):

Form	Behaviour	When to use
"interpolant" (default)	pybamm.Interpolant of the measured points, linear extrapolation	Default; data spans the operating concentration range
"landesfeind"	The Landesfeind form for that property, fitted to the data	Property must stay physical (positive/finite) below the lowest measured concentration (high-rate DFN depletion)

The dataset is treated as isothermal (single temperature), so each T-dependent Landesfeind form collapses to its isothermal reduction. The fitted form is property-specific — it is not the same exp for every property:

Property	Fitted isothermal form (c in mol.L-1)	Fit
Electrolyte conductivity [S.m-1]	q1·c·(1 + q2·√c + q3·c)/(1 + q4·c⁴)/10	nonlinear least squares
Electrolyte diffusivity [m2.s-1]	A·exp(B·c)	log-linear
Cation transference number	cubic polynomial in c	linear
Thermodynamic factor	cubic polynomial in c	linear

These mirror ionworkspipeline.direct_entries.landesfeind_electrolyte (which carries the full T-dependent forms with literature coefficients); here the coefficients are fitted to your dataset instead.

params = client.electrolyte.transport_from_dataset(
    "dataset-uuid",
    forms={
        # Diffusivity as the fitted Landesfeind exponential — finite down to
        # c_e = 0, so DFN stays stable when the electrolyte depletes at rate.
        "Electrolyte diffusivity [m2.s-1]": "landesfeind",
        # Conductivity as the fitted Landesfeind rational form.
        "Electrolyte conductivity [S.m-1]": "landesfeind",
        # Transference number stays tabulated (default).
    },
)

Default column mapping

By default these pybamm parameters are built from these dataset columns (concentration in mol.m-3):

pybamm parameter	dataset column
Electrolyte conductivity [S.m-1]	Electrolyte conductivity
Electrolyte diffusivity [m2.s-1]	Electrolyte diffusivity
Cation transference number	Transference number

Override the names (or build a subset) with columns and concentration_column:

params = client.electrolyte.transport_from_dataset(
    "dataset-uuid",
    columns={"Electrolyte conductivity [S.m-1]": "kappa"},
    concentration_column="c_e [mol.m-3]",
)

Use in a current-driven fit

Electrolyte transport is normally held fixed at these values while the fit floats particle diffusivity, exchange-current density, and active-material fractions. Merge the electrolyte parameters into the static DirectEntry:

electrolyte = client.electrolyte.transport_from_dataset(
    "dataset-uuid",
    forms={"Electrolyte diffusivity [m2.s-1]": "landesfeind"},
)

pipeline = iws.Pipeline(
    {
        "static": iws.direct_entries.DirectEntry(
            parameters={**constants, **dict(electrolyte)}
        ),
        # ... OCP interpolants, capacity calcs ...
        "fit": iws.DataFit(
            objectives={...},   # CurrentDriven on RPT / rate-ladder steps
            parameters={...},   # D_s, j0, eps_s — electrolyte stays fixed
            optimizer=iws.optimizers.DifferentialEvolution(),
        ),
    }
)

Inspecting the dataset first

# What columns and units does the dataset carry?
units = client.material_property_dataset.get_units("dataset-uuid")
df = client.material_property_dataset.get_data("dataset-uuid")
print(df.columns)

Notes and gotchas

• The returned functions take exactly (c_e, T). This signature is what lets ParameterValues.to_json() (called inside DirectEntry) infer the inputs. Do not hand-roll the lambdas with extra/default args — to_json treats those as model inputs and the solve fails later.
• A bare pybamm.Interpolant passed directly keeps its own dangling input and does not rebind to the model's c_e; always go through this helper (or a ParameterValues) so the symbol-JSON conversion happens.
• Concentration is assumed to be in mol.m-3 (the pybamm model convention). The "landesfeind" fits convert internally to mol.L-1 to match the published forms.
• The fit is isothermal — the returned functions ignore T. For the full temperature-dependent Landesfeind forms with literature coefficients, use ionworkspipeline.direct_entries.landesfeind_electrolyte(c_e, system) instead (server/local pipeline only).

Related skills

• discover-api — query the API, list materials and datasets
• manage-cells — material → component → cell-spec lookups
• run-simple-pipelines / manage-projects — submit the pipeline that consumes these parameters