Layups¶
A layup defines how electrodes and separators are arranged into a repeating unit. Layups handle N/P ratio control, electrode overhang, and areal capacity curve computation.
| Type | Description | Typical Use |
|---|---|---|
Laminate |
Two separators sandwiching cathode and anode | Wound cells |
MonoLayer |
Single separator between cathode and anode | Stacked cells |
ZFoldMonoLayer |
Z-fold separator variant | Z-fold stacks |
Control Modes & Enums¶
Overhang Utilities¶
Overhang control utilities for managing electrode and separator overhang behavior.
Classes¶
Bases: Enum
Control modes for overhang adjustments.
Attributes¶
FIXED_COMPONENT : str Adjusting overhangs moves component positions (keeps dimensions fixed) FIXED_OVERHANGS : str Adjusting overhangs changes component dimensions (keeps positions centered)
Mixin providing overhang management for layup components.
This mixin adds properties and methods to calculate, get, and set overhangs for anode and separator components relative to the cathode reference electrode.
Overhang Conventions¶
- Positive overhang: Component extends beyond cathode in that direction
- Negative overhang: Component recessed relative to cathode
- Units: Internal storage in meters, exposed properties in millimeters
Control Modes¶
FIXED_COMPONENT: Adjusting overhangs moves component positions while keeping their dimensions fixed. This is the default mode.
FIXED_OVERHANGS
Adjusting overhangs changes component dimensions while keeping their positions centered relative to the cathode.
Components Managed¶
- anode: Anode electrode overhangs (precision: 2 decimal places)
- bottom_separator: Bottom separator overhangs (precision: 3 decimal places)
- top_separator: Top separator overhangs (precision: 3 decimal places)
Properties Added¶
For each component and direction (left/right/bottom/top):
- {component}overhang : float Get/set overhang value in mm
- {component}overhang_range : Tuple[float, float] Valid (min, max) range for overhang in mm
- {component}_overhangs : dict Dictionary of all four overhangs for the component
- overhang_control_mode : OverhangControlMode Current control mode for overhang adjustments
Methods¶
_calculate_coordinates() Calculate all overhang values after coordinate setup _calculate_anode_overhangs() Calculate anode overhangs relative to cathode _calculate_bottom_separator_overhangs() Calculate bottom separator overhangs _calculate_top_separator_overhangs() Calculate top separator overhangs _compute_electrode_overhangs(ref, target) Compute overhangs between rectangular electrodes _compute_separator_overhangs(ref, separator) Compute overhangs between electrode and polygon separator _set_overhang(component, direction, overhang) Set overhang for any component and direction _adjust_overhang_fixed_component(component, overhang, direction) Adjust overhang by moving component position _adjust_overhang_fixed_overhangs(component, overhang, direction) Adjust overhang by changing component dimensions
Notes¶
This mixin should be placed early in the method resolution order (MRO) to ensure proper override of _calculate_coordinates() and calling of super() methods.
When using FIXED_COMPONENT mode, the component's datum position is adjusted. When using FIXED_OVERHANGS mode, the component's dimensions (x_foil_length, y_foil_length for electrodes; width, length for separators) are adjusted.
Special handling exists for ZFoldMonoLayer: when the anode moves left/right in FIXED_COMPONENT mode, the top separator follows to maintain the fold structure.
Examples¶
layup.overhang_control_mode = OverhangControlMode.FIXED_COMPONENT layup.anode_overhang_left = 2.5 # mm print(layup.anode_overhangs)
Switch to FIXED_OVERHANGS mode¶
layup.overhang_control_mode = OverhangControlMode.FIXED_OVERHANGS layup.anode_overhang_right = 3.0 # Extends anode width print(layup.anode.current_collector.x_foil_length) 152.0 # Width increased
Initialize overhang control mode to default value.
Sets the overhang control mode to FIXED_COMPONENT, where adjusting overhangs moves component positions rather than changing dimensions.
Attributes¶
property
writable
¶
overhang_control_mode: OverhangControlMode
property
writable
¶
Get the left overhang of the anode relative to the cathode in mm.
Returns¶
float Left overhang in mm. Positive values indicate anode extends beyond cathode.
property
writable
¶
Get the right overhang of the anode relative to the cathode in mm.
Returns¶
float Right overhang in mm. Positive values indicate anode extends beyond cathode.
property
writable
¶
Get the bottom overhang of the anode relative to the cathode in mm.
Returns¶
float Bottom overhang in mm. Positive values indicate anode extends beyond cathode.
property
writable
¶
Get the top overhang of the anode relative to the cathode in mm.
Returns¶
float Top overhang in mm. Positive values indicate anode extends beyond cathode.
property
¶
Get all anode overhangs as a dictionary.
Returns¶
dict Dictionary with keys 'left', 'right', 'bottom', 'top' and overhang values in mm.
property
¶
Get the valid range for left anode overhang based on control mode.
Returns¶
tuple (min, max) overhang range in mm. FIXED_OVERHANGS: (0, 20) FIXED_COMPONENT: (0, left + right overhang total)
property
¶
Get the valid range for right anode overhang based on control mode.
Returns¶
tuple (min, max) overhang range in mm. FIXED_OVERHANGS: (0, 20) FIXED_COMPONENT: (0, left + right overhang total)
property
¶
Get the valid range for bottom anode overhang based on control mode.
Returns¶
tuple (min, max) overhang range in mm. FIXED_OVERHANGS: (0, 20) FIXED_COMPONENT: (0, bottom + top overhang total)
property
¶
Get the valid range for top anode overhang based on control mode.
Returns¶
tuple (min, max) overhang range in mm. FIXED_OVERHANGS: (0, 20) FIXED_COMPONENT: (0, bottom + top overhang total)
property
writable
¶
Get the left overhang of the bottom separator relative to the cathode in mm.
Returns¶
float Left overhang in mm. Positive values indicate separator extends beyond cathode.
property
writable
¶
Get the right overhang of the bottom separator relative to the cathode in mm.
Returns¶
float Right overhang in mm. Positive values indicate separator extends beyond cathode.
property
writable
¶
Get the bottom overhang of the bottom separator relative to the cathode in mm.
Returns¶
float Bottom overhang in mm. Positive values indicate separator extends beyond cathode.
property
writable
¶
Get the top overhang of the bottom separator relative to the cathode in mm.
Returns¶
float Top overhang in mm. Positive values indicate separator extends beyond cathode.
property
¶
Get all bottom separator overhangs as a dictionary.
Returns¶
dict Dictionary with keys 'left', 'right', 'bottom', 'top' and overhang values in mm.
property
¶
Get the valid range for left bottom separator overhang based on control mode.
Returns¶
tuple (min, max) overhang range in mm. FIXED_OVERHANGS: (0, 20) or (0, 500) for Laminate FIXED_COMPONENT: (0, left + right overhang total)
property
¶
Get the valid range for right bottom separator overhang based on control mode.
Returns¶
tuple (min, max) overhang range in mm. FIXED_OVERHANGS: (0, 20) or (0, 500) for Laminate FIXED_COMPONENT: (0, left + right overhang total)
property
¶
Get the valid range for bottom bottom separator overhang based on control mode.
Returns¶
tuple (min, max) overhang range in mm. FIXED_OVERHANGS: (0, 20) FIXED_COMPONENT: (0, bottom + top overhang total)
property
¶
Get the valid range for top bottom separator overhang based on control mode.
Returns¶
tuple (min, max) overhang range in mm. FIXED_OVERHANGS: (0, 20) FIXED_COMPONENT: (0, bottom + top overhang total)
property
writable
¶
Get the left overhang of the top separator relative to the cathode in mm.
Returns¶
float Left overhang in mm. Positive values indicate separator extends beyond cathode.
property
writable
¶
Get the right overhang of the top separator relative to the cathode in mm.
Returns¶
float Right overhang in mm. Positive values indicate separator extends beyond cathode.
property
writable
¶
Get the bottom overhang of the top separator relative to the cathode in mm.
Returns¶
float Bottom overhang in mm. Positive values indicate separator extends beyond cathode.
property
writable
¶
Get the top overhang of the top separator relative to the cathode in mm.
Returns¶
float Top overhang in mm. Positive values indicate separator extends beyond cathode.
property
¶
Get all top separator overhangs as a dictionary.
Returns¶
dict Dictionary with keys 'left', 'right', 'bottom', 'top' and overhang values in mm.
property
¶
Get the valid range for left top separator overhang based on control mode.
Returns¶
tuple (min, max) overhang range in mm. FIXED_OVERHANGS: (0, 20) or (0, 500) for Laminate FIXED_COMPONENT: (0, left + right overhang total)
property
¶
Get the valid range for right top separator overhang based on control mode.
Returns¶
tuple (min, max) overhang range in mm. FIXED_OVERHANGS: (0, 20) or (0, 500) for Laminate FIXED_COMPONENT: (0, left + right overhang total)
Laminate¶
Two-separator layup for wound cells.
Two-separator laminate layup for wound electrode assemblies.
Classes¶
Laminate(cathode: Cathode, bottom_separator: Separator, anode: Anode, top_separator: Separator, electrode_orientation: ElectrodeOrientation = TRANSVERSE, name: str = 'Layup')
Bases: _Layup
Two-separator electrode layup for wound cells. A Laminate sandwiches the cathode and anode between a top and bottom separator, forming the repeating unit that is wound into a jelly roll.
Attributes¶
property
writable
¶
bottom_separator: Separator
Get the bottom separator of the laminate.
Methods:¶
Vectorized construction of flattened center lines for laminate layers.
Builds an explicit bottom->top ordered stack and computes center line elevations using cumulative thickness. This replaces the prior per-layer search for a single "supporting" component and removes duplication.
Parameters¶
x_spacing : float, optional Sampling resolution along the x-axis in meters. Determines the spacing between interpolation points for thickness calculations. Smaller values provide higher resolution but increase computation time. Default is 0.004 meters (4mm).
Returns¶
dict Dictionary mapping layer names to their flattened center line coordinates. Keys include component names like 'cathode_current_collector', 'anode_b_side_coating', etc.
Notes¶
- Currently no smoothing is applied (keeps geometric fidelity). A future enhancement could expose smoothing parameters.
- Stores auxiliary arrays for rapid thickness interpolation.
- The sampling resolution affects the accuracy of thickness calculations via get_thickness_at_x().
Return local laminate thickness at a given unwrapped x-position (meters).
Uses precomputed top surface (baseline + cumulative layer thickness) for O(log N) interpolation instead of scanning individual layers. Returns THICKNESS_FALLBACK if x is outside the sampled domain or no layers present.
Mono Layers¶
Single-separator layups for stacked cells.
Single-separator layup configurations for stacked electrode assemblies.
Classes¶
MonoLayer(cathode: Cathode, anode: Anode, separator: Separator, electrode_orientation: ElectrodeOrientation = LONGITUDINAL, name: str = 'MonoLayer')
Bases: _Layup
Class for a MonoLayer, which is a combination of anode, cathode, and separator. This class represents the item which will be repeated in space to form a z-fold stack.
Initialize the MonoLayer with the given components.
Parameters¶
cathode : Cathode The cathode component of the monolayer. anode : Anode The anode component of the monolayer. separator : Separator The separator component of the monolayer. electrode_orientation : ElectrodeOrientation The orientation of the electrode (default: ElectrodeOrientation.LONGITUDINAL). name : str, optional Name of the monolayer (default: "MonoLayer").
Attributes¶
property
writable
¶
separator: Separator
Unified separator interface (canonical); setting updates both top and bottom separators.
Returns the canonical separator (bottom instance for consistency).
Methods:¶
classmethod
¶
from_zfold_monolayer(zfold_monolayer: ZFoldMonoLayer) -> MonoLayer
Create a MonoLayer instance from a ZFoldMonoLayer instance.
Parameters¶
zfold_monolayer : ZFoldMonoLayer The ZFoldMonoLayer instance to convert.
Returns¶
MonoLayer A new MonoLayer instance with the same properties as the input ZFoldMonoLayer.
Notes¶
ZFoldMonoLayer uses non-rotated separators (_rotated_xy=False) where width -> y-direction. MonoLayer uses rotated separators (_rotated_xy=True) where width -> x-direction. This method swaps width and length values and rotates to match MonoLayer's coordinate system.
ZFoldMonoLayer(cathode: Cathode, anode: Anode, separator: Separator, electrode_orientation: ElectrodeOrientation = LONGITUDINAL, name: str = 'ZFoldMonoLayer')
Bases: MonoLayer
Z-fold variant of MonoLayer with constrained separator geometry.
Differences from MonoLayer:
- Canonical separator is NOT rotated; keep original orientation.
- Bottom separator length = cathode current collector width + 2 * canonical thickness.
- Top separator length = anode current collector width + 2 * canonical thickness.
- Unified separator API identical to MonoLayer (use separator property).
- Overhang setters behave the same; left/right still adjustable if needed.
Attributes¶
property
writable
¶
separator: Separator
Unified separator interface (canonical); setting updates both top and bottom separators.
Methods:¶
classmethod
¶
from_monolayer(monolayer: MonoLayer) -> ZFoldMonoLayer
Create a ZFoldMonoLayer instance from a MonoLayer instance.
Parameters¶
monolayer : MonoLayer The MonoLayer instance to convert.
Returns¶
ZFoldMonoLayer A new ZFoldMonoLayer instance with the same properties as the input MonoLayer.
Notes¶
MonoLayer uses rotated separators (_rotated_xy=True) where width -> x-direction. ZFoldMonoLayer uses non-rotated separators (_rotated_xy=False) where width -> y-direction. This method swaps width and length values when the source separator is rotated to preserve the physical dimensions correctly.