Monte carlo

make_manufacturing_variations

make_manufacturing_variations(
    base_design,
    n_samples=10,
    bound_range=0.05,
    sigma_fraction=None,
    seed=None,
    param_pairs=None,
    round_ndigits=5,
    eps=1e-12,
    design_name_format="MC Variation sample #%i",
    preserve_np_ratio=True,
)

Returns a list of dicts. Each dict contains the parameters that changed (vs. base_design) for that Monte Carlo sample, plus a designName.

• Auto-detects anode/cathode numeric pairs by matching "anode{S}" with "cathode{S}".
• Each parameter varies independently.
• Values are clipped to ±bound_range around base values.
• Includes a "designName" for each sample.

Parameters:

Name	Type	Description	Default
base_design	dict[str, Any]	The base design dictionary.	required
n_samples	int	Number of samples to generate. Defaults to 10.	10
bound_range	float | list[float]	Sample variations are bound between ± this fraction of the base value. A list of fractions for each parameter can be provided, or, a single number in which case that fraction is used for all parameters. Defaults to 0.05.	0.05
sigma_fraction	float | list[float] | None	The width of the normal distribution sampled. A list of fractions for each parameter can be provided, or, a single number in which case that width is used for all parameters. Defaults to None.	None
param_pairs	list[tuple[str, str]] | None	A list of parameters to vary. Each entry just be a pair of parameters for the anode and cathode, where the strings match keys in the base design. If None are provided, the list is inferred by selecting pairs of parameters from the base design that start with anode and cathode. Defaults to None.	None
round_ndigits	int	Defaults to 5.	5
eps	float	Defaults to 1e-12.	1e-12
design_name_format	str	A format string used to generate the design name for each sample, which must contain a single %i for the sample number (which starts from 1). Defaults to "MC Variation sample #%i" e.g. which would cause the first sample to have design name "MC Variation sample #1".	'MC Variation sample #%i'
preserve_np_ratio	bool	Whether or not the NP ratio of the designs should be preserved. If a design would alter the NP ratio and preserve_np_ratio is False, then simulations using that design will be failed	True

Returns:

Name	Type	Description
design_changes	list[dict[str, float]]	List of design changes for each sample.

plot_capacity_histogram

plot_capacity_histogram(df, title='Distribution of Capacity [Ah]', bins=20)

Plot a histogram of capacity values [Ah] across all designs.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame with KPI names as the index (rows). Must contain 'Capacity [Ah]' as a row.	required
title	str	Title for the plot.	'Distribution of Capacity [Ah]'
bins	int	Number of histogram bins.	20

Returns:

Type	Description
Figure	A Plotly figure object.

plot_capacity_resistance_heatmap

plot_capacity_resistance_heatmap(
    kpi_df,
    dcir_df,
    changes,
    base_design,
    capacity_row_label="Capacity [Ah]",
    resistance_col="Resistance (Ω)",
    design_col="Design",
    include_baseline=True,
    bins=(30, 30),
    title="Capacity vs DCIR",
    marker_size=8,
)

Heatmap-style scatter: Capacity [Ah] on x, Resistance (Ω) on y, hover shows the varied design parameters for each sample.

Parameters:

Name	Type	Description	Default
kpi_df	DataFrame	KPIs dataframe.	required
dcir_df	DataFrame	DCIR dataframe.	required
changes	list[dict[str, Any]]	List of design changes generated by 'make_manufacturing_variations'.	required
base_design	dict[str, Any]	Base design dictionary.	required
capacity_row_label	str	Capacity row label. Defaults to "Capacity [Ah]".	'Capacity [Ah]'
resistance_col	str	Resistance column label. Defaults to "Resistance (Ω)".	'Resistance (Ω)'
design_col	str	Design column label. Defaults to "Design".	'Design'
include_baseline	bool	Whether to include the baseline design. Defaults to True.	True
bins	tuple[int, int]	Number of bins for the x and y axes. Defaults to (30, 30).	(30, 30)
title	str	Plot title. Defaults to "Capacity vs DCIR".	'Capacity vs DCIR'
marker_size	int	Marker size. Defaults to 8.	8

Raises:

Type	Description
KeyError	If the capacity row label is not found in the kpi_df index.

Returns:

Type	Description
Figure	A Plotly figure object.

plot_dcir_histogram

plot_dcir_histogram(df, title='Distribution of DCIR', bins=20, include_baseline=True)

Plot a histogram of DCIR resistance values across all designs.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame with at least "Resistance (Ω)" column. Also should contain a "Design" column.	required
title	str	Title for the plot.	'Distribution of DCIR'
bins	int	Number of histogram bins.	20
include_baseline	bool	Whether to include 'Baseline' in the histogram.	True

Returns:

Type	Description
Figure	A Plotly figure object.

plot_scatter_matrix

plot_scatter_matrix(
    base_design,
    changes,
    param_keys,
    title="Manufacturing variations",
    marker_size=6,
    tickangle=-45,
)

Create a Plotly scatter-plot matrix (SPLOM) for selected parameters.

Parameters:

Name	Type	Description	Default
base_design	dict[str, Any]	The base design dictionary, typically from 'api.get_design_parameters'.	required
changes	list[dict[str, Any]]	List of the design changes generated by 'make_manufacturing_variations'.	required
param_keys	list[str]	A list of parameter keys to plot.	required
title	str	Plot title. Defaults to "Manufacturing variations".	'Manufacturing variations'
tickangle	int | None	Tilt labels if needed. Defaults to -45.	-45

Returns:

Type	Description
Figure	A Plotly figure object.

plot_variation_histograms

plot_variation_histograms(
    base_design,
    changes,
    param_keys,
    title="Distribution of Manufacturing Variations",
    bins=30,
)

Create a 2×2 subplot of histograms for selected parameters.

Use this function to visualise the samples generated by 'make_manufacturing_variations'.

Parameters:

Name	Type	Description	Default
base_design	dict[str, Any]	The base design dictionary, typically from 'api.get_design_parameters'.	required
changes	list[dict[str, Any]]	The list of design changes generated by 'make_manufacturing_variations'.	required
param_keys	list[str]	A list of parameter keys to plot.	required
title	str	Plot title. Defaults to "Distribution of Manufacturing Variations".	'Distribution of Manufacturing Variations'
bins	int	Number of bins in the histograms. Defaults to 30.	30

Returns:

Type	Description
Figure	A Plotly figure object.