Materials & property datasets

What are materials?

A Material is a reusable record describing a physical material used in a cell specification — for example, an NMC811 cathode powder, a graphite anode, or an LP57 electrolyte. Materials and their wrapping cell components (anode, cathode, electrolyte, separator, case) are scoped to a project. When you create a material or component through a cell specification, two projects in the same organization each get their own copy of the “same” material — same name, manufacturer, and product ID — so edits, property datasets, and cell references stay cleanly separated per project. Reusing a material across projects means creating a matching material in each project.

Materials and components created directly (not through a cell specification) don’t take a project, and remain organization-wide. Older materials predating per-project scoping may also still be organization-wide and shared across specs in different projects — editing one of these shared records affects every spec that references it.

Each material can have any number of property datasets attached to it. A property dataset is a tabular measurement (CSV or parquet) of one or more physical properties as a function of one or more independent variables — for example, electrolyte conductivity vs. concentration, or anode OCP vs. stoichiometry. Property datasets belong to the same project as their parent material.

Property datasets are stored as data — they are separate from parameter interpolants, which embed lookup tables directly into a parameterized model. Use property datasets to organize and share raw measurements, then turn them into interpolants when you are ready to use them in a simulation.

When to use materials

Use materials when you want to:

Keep a single source of truth for properties of a material used across multiple cells (e.g. the same electrolyte in several cell builds).
Store raw measurements (OCP, diffusivity, conductivity, transference number, …) alongside the material they were measured on.
Compare multiple datasets for the same property — for example, OCP curves measured at different temperatures or by different labs.
Track provenance: who uploaded a dataset, when, and from which raw file.

Managing materials in the UI

Each project has a Materials section in the left navigation. From there you can:

Create a material — give it a name, and optionally a manufacturer and product ID.
Open a material — view its property datasets and metadata.
Edit or delete a material from the row actions menu.

Materials created from the cell specification editor inherit the project of the cell spec, so you rarely need to pick a project explicitly — the material is created in the same project as the cell using it.

Uploading a property dataset

From a material’s detail page, click Upload property dataset and:

Pick a file — CSV or parquet. CSVs may include or omit a header row. When you select a file, the dataset name is prefilled from the file name; edit it if you want something different.
Review the dataset name — prefilled from the file name in step 1; change it if you want something different (e.g. Conductivity at 25 °C).
Declare columns — every column detected in the file is listed in order. For each one, provide:
- Name — the display name stored in the processed dataset (e.g. c_e). Every listed column must have a name before you can submit — drop the row for any column you don’t want to import, or name it and ignore it later. Trailing empty columns (a common Excel “trailing comma” artifact) are trimmed automatically.
- Unit — the physical unit (e.g. mol/L, S/m). Leave blank for dimensionless quantities.
- Source column — the column in the uploaded file the values come from. For headerless CSVs this is a position; for files with a header you can pick by name.
Submit. The file is parsed, every value is coerced to a floating-point number (non-numeric cells become NaN), and both the processed parquet and the original raw file are stored.

After upload, the dataset appears in the material’s property list with the number of rows and any NaN counts per column, so you can spot parsing issues quickly.

Plotting a dataset

Click a dataset to open the plot dialog. You can:

Pick the x and y columns from the dataset. The legend shows each y column with its unit (e.g. kappa (S/m)) so dual-axis plots are easy to read.
Zoom and pan; the plot dynamically downsamples and re-fetches points for the visible range so large datasets stay responsive.
Download the processed parquet or the original raw file from the actions menu.

Editing a dataset

The Edit action on a dataset lets you:

Rename the dataset.
Re-declare column names and units. When columns change, the stored parquet is rebuilt from the preserved original file using the new specs — you do not need to re-upload.
Replace the data file entirely while keeping the same dataset ID and metadata. Other records that reference the dataset stay linked.

Each data-changing edit bumps the dataset’s data_version, so downstream consumers can detect when a cached result is stale.

Python client

The Python API client exposes materials and their property datasets as two sub-clients:

client.material — list and retrieve materials.
client.material_property_dataset — list, retrieve, and download property datasets.

Both clients are read-only. To create or modify materials and datasets, use the UI or the REST API.

Listing and retrieving materials

from ionworks import Ionworks

client = Ionworks()

# List materials in the current organization, across all your projects
materials = client.material.list(limit=50)
for m in materials:
    print(m.id, m.name, m.manufacturer, m.product_id, m.project_id)

# Retrieve a single material by ID
material = client.material.get("mat_abc123")

Each material carries a project_id. Pass project_id to list() to also scope the property_count returned on each material to that project.

Listing property datasets for a material

datasets = client.material_property_dataset.list(
    material_id="mat_abc123",
    project_id="proj_xyz789",  # optional: only datasets in this project
    limit=100,
)
for d in datasets:
    print(d.id, d.name, d.data_version, [c.name for c in d.columns])

Each MaterialPropertyDataset exposes its columns (a list of ColumnSpec records with name, unit, and source_column_index), the data_version that bumps on every edit, and per-column nan_counts.

Downloading dataset values

get_data() downloads the full dataset and returns it as a DataFrame in the configured DataFrame backend:

dataset = client.material_property_dataset.get("mpd_def456")
print(dataset.name, dataset.data_version)

# Map column name to physical unit, e.g. {"c_e": "mol/L", "kappa": "S/m"}
units = {col.name: col.unit for col in dataset.columns}

# Pull all rows as a DataFrame
df = client.material_property_dataset.get_data("mpd_def456")
df.head()

REST API

Material property datasets are managed under /material_property_datasets. Materials themselves are managed under /materials.

Upload a dataset

POST /material_property_datasets accepts a multipart form:

Field	Description
`file`	The CSV or parquet file to upload.
`material_id`	ID of the parent material.
`project_id`	ID of the project this dataset is scoped to.
`name`	Human-readable dataset name.
`columns`	JSON array of column specs (see below).
`no_header`	`true` if the CSV has no header row. Defaults to `false`.

Each column spec is an object:

{
  "name": "c_e",
  "unit": "mol.L-1",
  "source_column_index": 0
}

source_column_index is the 0-based position of the column in the uploaded file. It is required even when the file has a header row — names are matched by position, then renamed to the name you provide. Example upload with curl:

curl -X POST "$IONWORKS_URL/material_property_datasets" \
  -H "Authorization: Bearer $IONWORKS_API_KEY" \
  -F "[email protected]" \
  -F "material_id=$MATERIAL_ID" \
  -F "project_id=$PROJECT_ID" \
  -F "name=Conductivity at 25 °C" \
  -F 'columns=[
    {"name": "c_e", "unit": "mol.L-1", "source_column_index": 0},
    {"name": "kappa", "unit": "S.m-1", "source_column_index": 1}
  ]'

The response is the new dataset record, including its id, storage_path, data_version, and per-column nan_counts.

List datasets for a material

curl "$IONWORKS_URL/material_property_datasets?material_id=$MATERIAL_ID&project_id=$PROJECT_ID&limit=100&offset=0" \
  -H "Authorization: Bearer $IONWORKS_API_KEY"

Returns a paginated list of dataset records.

Fetch dataset values as JSON

curl "$IONWORKS_URL/material_property_datasets/$DATASET_ID/data?max_points=500&x_col=c_e&x_min=0&x_max=2" \
  -H "Authorization: Bearer $IONWORKS_API_KEY"

Returns the dataset as a column-major JSON object:

{
  "c_e": [0.5, 1.0, 1.5, 2.0],
  "kappa": [0.42, 0.71, 0.89, 0.95]
}

max_points downsamples uniformly so large datasets remain responsive to plot. x_col, x_min, and x_max restrict the response to a range of one column — useful for zooming charts.

Download the underlying file

Use GET /material_property_datasets/{id}/file to redirect to a short-lived signed URL for the file, or GET /material_property_datasets/{id}/download-url to receive the URL as JSON (handy when you want to open it from the browser). Pass ?kind=parquet (default) to download the processed parquet, or ?kind=original to download the raw file you uploaded.

Update metadata, replace the file, or delete

Endpoint	Description
`PATCH /material_property_datasets/{id}`	Rename the dataset and/or re-declare its columns. When columns change, the parquet is rebuilt from the preserved original file.
`PATCH /material_property_datasets/{id}/file`	Replace the data file. Optionally update `name`, `columns`, and `no_header` in the same request.
`DELETE /material_property_datasets/{id}`	Delete the dataset and its stored files.

Cells — materials are referenced from the anode, cathode, electrolyte, and separator components of a cell specification.
Parameter interpolants — turn measured property data into lookup-table parameters inside a parameterized model.
Electrolyte transport from a dataset — build concentration-dependent electrolyte transport parameters from a property dataset and drop them into a pipeline.
Data overview — how experimental data is organized in Ionworks Studio.

Get Started

Core Concepts

Data

Build

Pipelines

Simulate

Optimize

Materials & property datasets

What are materials?

When to use materials

Managing materials in the UI

Uploading a property dataset

Plotting a dataset

Editing a dataset

Python client

Listing and retrieving materials

Listing property datasets for a material

Downloading dataset values

REST API

Upload a dataset

List datasets for a material

Fetch dataset values as JSON

Download the underlying file

Update metadata, replace the file, or delete

​What are materials?

​When to use materials

​Managing materials in the UI

​Uploading a property dataset

​Plotting a dataset

​Editing a dataset

​Python client

​Listing and retrieving materials

​Listing property datasets for a material

​Downloading dataset values

​REST API

​Upload a dataset

​List datasets for a material

​Fetch dataset values as JSON

​Download the underlying file

​Update metadata, replace the file, or delete

​Related

What are materials?

When to use materials

Managing materials in the UI

Uploading a property dataset

Plotting a dataset

Editing a dataset

Python client

Listing and retrieving materials

Listing property datasets for a material

Downloading dataset values

REST API

Upload a dataset

List datasets for a material

Fetch dataset values as JSON

Download the underlying file

Update metadata, replace the file, or delete

Related