Cells

Complete battery cell models. Each cell type wraps one or more electrode assemblies inside an encapsulation, fills with electrolyte, and computes energy, mass, cost, and volumetric properties.

All cell types provide:

• Settable properties: operating_voltage_window, reversible_capacity, n_electrode_assembly, electrolyte_overfill
• Computed properties: energy, mass, cost, volume, specific_energy, volumetric_energy, cost_per_energy
• Visualization: get_cross_section(), get_top_down_view(), get_capacity_plot(), plot_mass_breakdown(), plot_cost_breakdown()

---

Cylindrical Cell

For round wound jelly rolls (e.g., 18650, 21700, 4680).

CylindricalCell

Cylindrical battery cell implementation.

Attributes

Classes

CylindricalCell

CylindricalCell(reference_electrode_assembly: WoundJellyRoll, encapsulation: CylindricalEncapsulation, electrolyte: Electrolyte, operating_voltage_window: Tuple[float, float] = (None, None), electrolyte_overfill: float = 20, name: str = 'Cylindrical Cell')

Bases: _Cell

Complete cylindrical battery cell (e.g., 18650, 21700, 4680 format). Combines a wound jelly roll with a cylindrical canister encapsulation and electrolyte.

Create a cylindrical cell with wound jelly roll electrode assembly.

Parameters

reference_electrode_assembly : WoundJellyRoll Electrochemical stack defining cell capacity and voltage behavior encapsulation : CylindricalEncapsulation Mechanical housing (canister, lid, terminals) defining external geometry electrolyte : Electrolyte Bulk electrolyte material with density and cost properties operating_voltage_window : Tuple[float, float] Operating voltage window (min_voltage, max_voltage) in volts electrolyte_overfill : float, optional Fractional overfill beyond pore volume (default: 20%) name : str, optional Display name for the cell (default: "Cylindrical Cell") n_electrode_assembly : int, optional Number of parallel electrode assemblies (default: 1)

Attributes

radius property writable

radius: float

Get the cell outer radius in mm.

radius_range property

radius_range: Tuple[float, float]

Get the valid range for cell radius in mm.

radius_hard_range property

radius_hard_range: Tuple[float, float]

Get the hard limit range for cell radius in mm.

diameter property writable

diameter: float

Get the cell outer diameter in mm.

diameter_range property

diameter_range: Tuple[float, float]

Get the valid range for cell diameter in mm.

diameter_hard_range property

diameter_hard_range: Tuple[float, float]

Get the hard limit range for cell diameter in mm.

height property writable

height: float

Get the cell height in mm.

height_range property

height_range: Tuple[float, float]

Get the valid range for cell height in mm.

height_hard_range property

height_hard_range: Tuple[float, float]

Get the hard limit range for cell height in mm.

reference_electrode_assembly property writable

reference_electrode_assembly: WoundJellyRoll

Get the reference wound jelly roll electrode assembly.

encapsulation property writable

encapsulation: CylindricalEncapsulation

Get the cylindrical encapsulation.

n_electrode_assembly property writable

n_electrode_assembly: int

Get the number of electrode assemblies (always 1 for cylindrical).

Methods:

fit_assembly_radius_to_canister

fit_assembly_radius_to_canister() -> None

Resize the jelly roll radius to match the canister inner radius.

fit_assembly_height_to_canister

fit_assembly_height_to_canister() -> None

Resize the jelly roll height to match the canister internal height.

fit_encapsulation_radius_to_assembly

fit_encapsulation_radius_to_assembly(clearance: float = 0) -> None

Fit the encapsulation radius to the electrode assembly.

Delegates to CylindricalEncapsulation.fit_radius() using the reference electrode assembly.

Parameters

clearance : float, optional Additional clearance in mm (default: 0)

fit_encapsulation_height_to_assembly

fit_encapsulation_height_to_assembly(clearance: float = 0) -> None

Fit the encapsulation internal height to the electrode assembly.

Delegates to CylindricalEncapsulation.fit_height() using the reference electrode assembly.

Parameters

clearance : float, optional Additional clearance in mm (default: 0)

plot_top_down_view

plot_top_down_view(**kwargs) -> Figure

Generate top down view plot showing encapsulation and jelly roll cross-section.

Parameters

**kwargs Additional layout options (paper_bgcolor, plot_bgcolor, title, etc.)

Returns

go.Figure Plotly figure with combined encapsulation and jelly roll traces

plot_cross_section

plot_cross_section(**kwargs) -> Figure

Generate cross-section view showing the spiral winding and canister.

---

Prismatic Cell

For flat-wound or stacked assemblies in hard-case housings.

PrismaticCell

Prismatic battery cell implementation.

Classes

PrismaticCell

PrismaticCell(reference_electrode_assembly: FlatWoundJellyRoll | ZFoldStack | PunchedStack, n_electrode_assembly: int, encapsulation: PrismaticEncapsulation, electrolyte: Electrolyte, operating_voltage_window: Tuple[float, float] = (None, None), clipped_tab_length: float = None, electrolyte_overfill: float = 20, name: str = 'Prismatic Cell')

Bases: _Cell

Prismatic hard-case battery cell. Supports both stacked and flat-wound jelly roll internal constructions with a rigid metal canister.

Create a prismatic cell with wound jelly roll or stacked electrode assembly.

Parameters

reference_electrode_assembly : FlatWoundJellyRoll | ZFoldStack | PunchedStack Electrochemical stack defining cell capacity and voltage behavior n_electrode_assembly : int Number of parallel electrode assemblies encapsulation : PrismaticEncapsulation Mechanical housing (canister, lid, terminals) defining external geometry electrolyte : Electrolyte Bulk electrolyte material with density and cost properties operating_voltage_window : Tuple[float, float] Operating voltage window (min_voltage, max_voltage) in volts clipped_tab_length : float, optional Length of clipped tabs in mm (default: None, uses full tab length) electrolyte_overfill : float, optional Fractional overfill beyond pore volume (default: 0.2 = 20%) name : str, optional Display name for the cell (default: "Prismatic Cell")

Attributes

length property writable

length: float

Get the cell length (depth) in mm.

length_range property

length_range: float

Get the valid range for cell length in mm.

length_hard_range property

length_hard_range: float

Get the hard limit range for cell length in mm.

width property writable

width: float

Get the cell width in mm.

width_range property

width_range: Tuple[float, float]

Get the valid range for cell width in mm.

width_hard_range property

width_hard_range: Tuple[float, float]

Get the hard limit range for cell width in mm.

n_electrode_assembly property writable

n_electrode_assembly: int

Get the number of electrode assemblies in the cell.

height property writable

height: float

Get the cell height in mm.

height_range property

height_range: Tuple[float, float]

Get the valid range for cell height in mm.

height_hard_range property

height_hard_range: Tuple[float, float]

Get the hard limit range for cell height in mm.

clipped_tab_length property writable

clipped_tab_length: float

Get clipped tab length.

clipped_tab_length_range property

clipped_tab_length_range: Tuple[float, float]

Get valid range for clipped tab length.

Returns

Tuple[float, float] (min, max) clipped tab length in mm. Maximum is limited by the shortest free (uncoated) tab length among cathode and anode.

reference_electrode_assembly property writable

reference_electrode_assembly: FlatWoundJellyRoll | ZFoldStack | PunchedStack

Get reference electrode assembly.

encapsulation property writable

encapsulation: PrismaticEncapsulation

Get encapsulation.

Methods:

plot_top_down_view

plot_top_down_view(opacity=0.3, **kwargs) -> Figure

Get top-down view figure of the prismatic cell.

Parameters

opacity : float Opacity level for all traces (0.0 to 1.0) kwargs : dict Additional keyword arguments for figure customization

Returns

go.Figure Plotly figure object representing the top-down view of the prismatic cell

plot_side_view

plot_side_view(**kwargs) -> Figure

Get side view figure of the prismatic cell.

Parameters

kwargs : dict Additional keyword arguments for figure customization

Returns

go.Figure Plotly figure object representing the side view of the prismatic cell

fit_encapsulation_height_to_assemblies

fit_encapsulation_height_to_assemblies(clearance: float = 0) -> None

Fit the encapsulation height to the electrode assemblies.

Delegates to PrismaticEncapsulation.fit_height() using the first electrode assembly (which has clipped tabs).

Parameters

clearance : float, optional Additional clearance in mm (default: 0)

fit_encapsulation_width_to_assemblies

fit_encapsulation_width_to_assemblies(clearance: float = 0) -> None

Fit the encapsulation width to the electrode assemblies.

Delegates to PrismaticEncapsulation.fit_width() using the reference electrode assembly.

Parameters

clearance : float, optional Additional clearance in mm (default: 0)

fit_encapsulation_length_to_assemblies

fit_encapsulation_length_to_assemblies(clearance: float = 0) -> None

Fit the encapsulation length to the electrode assemblies.

Delegates to PrismaticEncapsulation.fit_length() using the reference electrode assembly and n_electrode_assembly.

Parameters

clearance : float, optional Additional clearance in mm (default: 0)

---

Pouch Cell

For stacked assemblies in soft-pack laminate pouches.

PouchCell

Pouch (soft-pack) battery cell implementation.

Classes

PouchCell

PouchCell(reference_electrode_assembly: ZFoldStack | PunchedStack | FlatWoundJellyRoll, n_electrode_assembly: int, encapsulation: PouchEncapsulation, electrolyte: Electrolyte, operating_voltage_window: Tuple[float, float] = (None, None), side_seal_thickness: float = 5, top_seal_thickness: float = 5, bottom_seal_thickness: float = 5, clipped_tab_length: float = None, electrolyte_overfill: float = 20, name: str = 'Pouch Cell')

Bases: _Cell

Pouch (soft-pack) battery cell. Combines stacked electrode assemblies with laminate film encapsulation, terminals, and electrolyte.

Create a pouch cell with stacked electrode assembly.

Parameters

reference_electrode_assembly : ZFoldStack | PunchedStack | FlatWoundJellyRoll Electrochemical assembly defining cell capacity and voltage behavior. A flat wound jelly roll must already carry aligned notches. encapsulation : PouchEncapsulation Mechanical housing (canister, lid, terminals) defining external geometry electrolyte : Electrolyte Bulk electrolyte material with density and cost properties operating_voltage_window : Tuple[float, float] Operating voltage window (min_voltage, max_voltage) in volts electrolyte_overfill : float, optional Fractional overfill beyond pore volume (default: 0.2 = 20%) name : str, optional Display name for the cell (default: "Pouch Cell") n_electrode_assembly : int, optional Number of parallel electrode assemblies (default: 1)

Attributes

side_seal_thickness property writable

side_seal_thickness: float

Get side seal thickness.

side_seal_thickness_range property

side_seal_thickness_range: Tuple[float, float]

Get the valid range for side seal thickness in mm.

side_seal_thickness_hard_range property

side_seal_thickness_hard_range: Tuple[float, float]

Get the hard limit range for side seal thickness in mm.

top_seal_thickness property writable

top_seal_thickness: float

Get top seal thickness.

top_seal_thickness_range property

top_seal_thickness_range: Tuple[float, float]

Get the valid range for top seal thickness in mm.

top_seal_thickness_hard_range property

top_seal_thickness_hard_range: Tuple[float, float]

Get the hard limit range for top seal thickness in mm.

bottom_seal_thickness property writable

bottom_seal_thickness: float

Get bottom seal thickness.

bottom_seal_thickness_range property

bottom_seal_thickness_range: Tuple[float, float]

Get the valid range for bottom seal thickness in mm.

bottom_seal_thickness_hard_range property

bottom_seal_thickness_hard_range: Tuple[float, float]

Get the hard limit range for bottom seal thickness in mm.

reference_electrode_assembly property writable

reference_electrode_assembly: ZFoldStack | PunchedStack | FlatWoundJellyRoll

Get reference electrode assembly.

encapsulation property writable

encapsulation: PouchEncapsulation

Get encapsulation.

clipped_tab_length property writable

clipped_tab_length: Optional[float]

Get clipped tab length in mm, or None when the tabs are unclipped.

The setter accepts None (the constructor's default) and _clip_tabs treats it as "leave the tabs alone", so a pouch can legitimately have no clip length -- including any cell converted from another form factor, which cannot supply one it never had. Report that rather than raising on the arithmetic.

clipped_tab_length_range property

clipped_tab_length_range: Tuple[float, float]

Get valid range for clipped tab length.

Returns

Tuple[float, float] (min, max) clipped tab length in mm. Maximum is limited by the shortest free (uncoated) tab length among cathode and anode.

height property writable

height: float

Get the total cell height in mm (assembly + seals).

height_range property

height_range: float

Get the valid range for cell height in mm.

height_hard_range property

height_hard_range: float

Get the hard limit range for cell height in mm.

width property writable

width: float

Get the total cell width in mm (assembly + side seals).

width_range property

width_range: float

Get the valid range for cell width in mm.

width_hard_range property

width_hard_range: float

Get the hard limit range for cell width in mm.

thickness property writable

thickness: float

Get the total cell thickness in mm (assemblies + laminates).

thickness_range property

thickness_range: float

Get the valid range for cell thickness in mm.

thickness_hard_range property

thickness_hard_range: float

Get the hard limit range for cell thickness in mm.

Methods:

plot_side_view

plot_side_view(**kwargs) -> Figure

Get side view figure of the pouch cell.

Parameters

kwargs : dict Additional keyword arguments for figure customization

Returns

go.Figure Plotly figure object representing the side view of the pouch cell

plot_top_down_view

plot_top_down_view(opacity=0.3, **kwargs) -> Figure

Get top-down view figure of the pouch cell.

Parameters

opacity : float Opacity level for all traces (0.0 to 1.0) kwargs : dict Additional keyword arguments for figure customization

Returns

go.Figure Plotly figure object representing the top-down view of the pouch cell

---

Flex-Frame Cell

For solid-state cell designs with a flex-frame housing.

FlexFrameCell

Flex-frame battery cell implementation.

Classes

FlexFrameCell

FlexFrameCell(reference_electrode_assembly: PunchedStack, encapsulation: FlexFrameEncapsulation, catholyte: Electrolyte, operating_voltage_window: Tuple[float, float] = (None, None), clipped_tab_length: float = None, name: str = 'FlexFrame Solid State Cell')

Bases: _Cell

Flex-frame battery cell for solid-state or specialized designs. Uses a rigid polymer frame with laminate sealing instead of a metal canister.

Create a flex frame cell with stacked electrode assembly.

Parameters

reference_electrode_assembly : PunchedStack Electrochemical stack defining cell capacity and voltage behavior encapsulation : FlexFrameEncapsulation Mechanical housing (canister, lid, terminals) defining external geometry catholyte : Electrolyte Bulk electrolyte material with density and cost properties operating_voltage_window : Tuple[float, float] Operating voltage window (min_voltage, max_voltage) in volts name : str, optional Display name for the cell (default: "FlexFrame Solid State Cell")

Attributes

reference_electrode_assembly property writable

reference_electrode_assembly: PunchedStack

Get reference electrode assembly.

encapsulation property writable

encapsulation: FlexFrameEncapsulation

Get encapsulation.

n_electrode_assembly property writable

n_electrode_assembly: int

Get the number of electrode assemblies (always 1 for flex frame).

height property writable

height: float

Get the total cell height in mm (encapsulation height).

height_range property

height_range: Tuple[float, float]

Get the valid range for cell height in mm.

height_hard_range property

height_hard_range: Tuple[float, float]

Get the hard limit range for cell height in mm.

width property writable

width: float

Get the total cell width in mm (encapsulation width).

width_range property

width_range: Tuple[float, float]

Get the valid range for cell width in mm.

width_hard_range property

width_hard_range: Tuple[float, float]

Get the hard limit range for cell width in mm.

thickness property writable

thickness: float

Get the total cell thickness in mm (assembly + laminates).

thickness_range property

thickness_range: Tuple[float, float]

Get the valid range for cell thickness in mm.

thickness_hard_range property

thickness_hard_range: Tuple[float, float]

Get the hard limit range for cell thickness in mm.

clipped_tab_length property writable

clipped_tab_length: float

Get clipped tab length.

clipped_tab_length_range property

clipped_tab_length_range: Tuple[float, float]

Get valid range for clipped tab length.

Returns

Tuple[float, float] (min, max) clipped tab length in mm. Maximum is limited by the shortest free (uncoated) tab length among cathode and anode.

Methods:

plot_side_view

plot_side_view(**kwargs) -> Figure

Get side view figure of the flex frame cell.

Parameters

kwargs : dict Additional keyword arguments for figure customization

Returns

go.Figure Plotly figure object representing the side view of the flex frame cell

plot_top_down_view

plot_top_down_view(opacity=0.3, **kwargs) -> Figure

Get top-down view figure of the flex frame cell.

Parameters

opacity : float Opacity level for all traces (0.0 to 1.0) kwargs : dict Additional keyword arguments for figure customization

Returns

go.Figure Plotly figure object representing the top-down view of the flex frame cell