Skip to content

Basic usage

A short path from install to a loaded cell. For plots and longer workflows, use the Tutorials. Example notebooks and data also live in the examples folder on GitHub (cellpy pull can download them).

Load a cell

Prefer bundled example data when trying the library for the first time (needs network on first download):

from cellpy.utils import example_data

c = example_data.raw_file()  # Arbin .res → CellpyCell with steps + summary

Or load a path you already have:

import cellpy

c = cellpy.get(
    "path/to/my_cell.res",
    mass=0.982,  # active material mass in mg
    instrument="arbin_res",  # optional; often inferred from the suffix
)

cellpy.get loads the file, builds the step table, and creates the per-cycle summary (unless you opt out with keyword arguments).

Inspect frames and schema

Measurement tables live on c.data. Prefer c.schema for column names so code tracks the active schema (native cellpy-core names in 2.x):

print(c.data.summary.head())
print(c.get_cycle_numbers()[:5])

potential = c.data.raw[c.schema.raw.potential]
charge_cap = c.data.summary[c.schema.summary.charge_capacity]

Hard-coding 1.x header strings is brittle — see Coming from cellpy 1.x and the legacy header map.

Save and export

Save a tester-agnostic cellpy file (2.x default is the v9 zip-of-parquet .cellpy format; HDF5 remains readable):

c.save("out/my_cell.cellpy")

CSV export:

c.to_csv("out/csv_export")

Frames are pandas DataFrames, so you can also use DataFrame.to_excel / to_csv on c.data.raw, .steps, or .summary directly. CellpyCell also exposes to_excel for a packaged export.

Cycles and curves

cycles = c.get_cycle_numbers()
print(f"{len(cycles)} cycles")

cap = c.get_cap(5)  # capacity–voltage for cycle 5
ocv = c.get_ocv(ocv_type="ocvrlx_up", cycle_number=44)

More extractors (get_current, get_voltage, split, merge, …) are on CellpyCell — see the API reference and Tutorials.

Next steps