Skip to main content

​
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 live at the organization level so the same material can be referenced from multiple cells and projects. 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 are scoped to a project, so each project can keep its own measurements for the same shared 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.
System materials (shared across all organizations) are read-only and appear alongside your organization’s materials when relevant.

​
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.
  2. Name the dataset — for example, Conductivity at 25 °C.
  3. Declare columns — for each column you want to keep, provide:
    • Name — the display name stored in the processed dataset (e.g. c_e).
    • 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.
  • 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.

​
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:
FieldDescription
fileThe CSV or parquet file to upload.
material_idID of the parent material.
project_idID of the project this dataset is scoped to.
nameHuman-readable dataset name.
columnsJSON array of column specs (see below).
no_headertrue if the CSV has no header row. Defaults to false.
Each column spec is an object: 
{
  "name": "c_e",
  "unit": "mol/L",
  "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_TOKEN" \
  -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", "source_column_index": 0},
    {"name": "kappa", "unit": "S/m", "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_TOKEN"
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_TOKEN"
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

EndpointDescription
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}/fileReplace 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.
  • Data overview — how experimental data is organized in Ionworks Studio.