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

# Materials & property datasets

> Manage electrode, electrolyte, and other materials and attach measured property datasets like OCP, diffusivity, and conductivity curves

## What are materials?

A **Material** is a reusable record describing a physical material used in a
[cell specification](/core-concepts/cells) — 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.

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

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.

<Note>
  Property datasets are stored as data — they are separate from
  [parameter interpolants](/build/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.
</Note>

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

1. **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.
2. **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`).
3. **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.
4. **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](/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](#rest-api).

### Listing and retrieving materials

```python theme={null}
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

```python theme={null}
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](/api-client#dataframe-backend):

```python theme={null}
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:

```json theme={null}
{
  "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`:

```bash theme={null}
curl -X POST "$IONWORKS_URL/material_property_datasets" \
  -H "Authorization: Bearer $IONWORKS_API_KEY" \
  -F "file=@conductivity.csv" \
  -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

```bash theme={null}
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

```bash theme={null}
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:

```json theme={null}
{
  "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.                                                                                        |

## Related

* [Cells](/core-concepts/cells) — materials are referenced from the anode,
  cathode, electrolyte, and separator components of a cell specification.
* [Parameter interpolants](/build/interpolants) — turn measured property data
  into lookup-table parameters inside a parameterized model.
* [Electrolyte transport from a dataset](/pipelines/direct-entries#building-electrolyte-transport-from-a-material-dataset)
  — build concentration-dependent electrolyte transport parameters from a
  property dataset and drop them into a pipeline.
* [Data overview](/data/overview) — how experimental data is organized in
  Ionworks Studio.