upxo.gsContainters.mcgs2Cont module

mcgs2Cont.py — Container for 2-D Monte-Carlo grain-structure temporal datasets.

Default import:

import upxo.gsContainters.mcgs2Cont as gs_cntnr2_mc

Typical usage:

cntr = gs_cntnr2_mc.MC_GS_Container2d.by_upxoMCSIM_gsset_GEN(
    indb='path/to/dashboard.xls',
    mctimeStart=2, mctimeStep=1, mctimeEnd=-1,
)
fig, axes = cntr.plot_temporal_distributions(props=['area', 'aspect_ratio'])
plt.show()
class upxo.gsContainters.mcgs2Cont.MC_GS_Container2d[source]

Bases: object

Container for a set of characterised 2-D MC grain structures spanning a range of Monte-Carlo time slices.

indb

Path to the UPXO input-dashboard Excel file.

Type:

str

gsset

{tslice: mcgs2_grain_structure} — characterised grain structures keyed by MC time-step index.

Type:

dict

mctimeStart

First MC time-slice index included.

Type:

int

mctimeStep

Stride between included time slices.

Type:

int

mctimeEnd

Last MC time-slice index (exclusive). -1 collects to the penultimate slice.

Type:

int

char_kwargs

Keyword arguments passed to char_morph_2d() for every slice.

Type:

dict

Notes

Do not call __init__ directly. Use the class-method constructor by_upxoMCSIM_gsset_GEN().

classmethod by_upxoMCSIM_gsset_GEN(indb: str, upxoMCSIM_gsset=None, mctimeStart: int = 2, mctimeStep: int = 1, mctimeEnd: int = -1, **kwargs) → MC_GS_Container2d[source]

Build a container by running (or reusing) a 2-D MC grain-growth simulation and characterising every selected temporal slice.

Parameters:

  • indb (str) – Path to the UPXO input-dashboard Excel file used to drive the MC simulation.

  • upxoMCSIM_gsset (mcgs or None, optional) – A pre-existing mcgs object whose simulation has already been run and whose grains have been detected. When None (default) a fresh simulation is run using indb.

  • mctimeStart (int, optional) – Index into pxt.m from which to start collecting slices. Default 2 (skips the initial, unpopulated slices).

  • mctimeStep (int, optional) – Stride between collected time slices. Default 1.

  • mctimeEnd (int, optional) – Index into pxt.m at which to stop (exclusive). -1 (default) collects up to but not including the last slice.

  • **kwargs –

    Overrides for char_morph_2d() keyword arguments. Any key not supplied falls back to the defaults listed below.

    use_version=2,
bbox=True,                   bbox_ex=False,
npixels=True,                identify_pixel_locations=True,
npixels_gb=False,
area=True,                   aspect_ratio=True,
solidity=True,               major_axis_length=True,
minor_axis_length=True,
circularity=False,           eccentricity=False,
euler_number=False,          moments_hu=False,
append=False,                saa=True,
throw=False,                 char_grain_positions=False,
find_neigh=False,            char_gb=False,
make_skim_prop=True,         get_grain_coords=True,

Returns:

Populated container with gsset keyed by MC time-step index.

Return type:

MC_GS_Container2d

Notes

The underlying mcgs simulation object is deleted after characterisation to free memory.

Examples

>>> import upxo.gsContainters.mcgs2Cont as gs_cntnr2_mc
>>> cntr = gs_cntnr2_mc.MC_GS_Container2d.by_upxoMCSIM_gsset_GEN(
...     indb='path/to/dashboard.xls',
...     mctimeStart=2, mctimeStep=2, mctimeEnd=-1,
...     circularity=True,
... )
plot_temporal_distributions(props: list[str] | None = None, ncols: int = 2, figsize_per: tuple[float, float] = (5, 4), dpi: int = 110, bins: int = 40, bw_method: str | float = 'scott', peak_prominence: float = 0.01, fontsize: float = 10.0, suptitle: str = 'Temporal evolution of grain-property distributions', cmap: str = 'nipy_spectral', show_stats_table: bool = True)[source]

Plot KDE distributions — one curve per temporal slice — overlaid for each selected morphological property. No histograms; no on-graph peak markers. A single vertical colorbar maps line colour to MC time-slice index. After the figure a summary statistics table is printed and stored in stats_table.

Parameters:

  • props (list of str, optional) – Property names to plot. Defaults to all properties that were enabled at characterisation time (via char_kwargs). Valid values: 'area', 'aspect_ratio', 'solidity', 'major_axis_length', 'minor_axis_length', 'circularity', 'eccentricity'.

  • ncols (int, optional) – Number of subplot columns. Default 2.

  • figsize_per (tuple of float, optional) – (width, height) in inches per panel. Default (5, 4).

  • dpi (int, optional) – Figure resolution. Default 110.

  • bins (int, optional) – Bin count used only for computing the shared x-range. Default 40.

  • bw_method (str or float, optional) – Bandwidth selector for scipy.stats.gaussian_kde. Default 'scott'.

  • peak_prominence (float, optional) – Fraction of KDE maximum used as minimum peak prominence when computing the dominant-peak value for the statistics table. Default 0.01.

  • fontsize (float, optional) – Base font size. Default 10.0.

  • suptitle (str, optional) – Figure-level title.

  • cmap (str, optional) – Matplotlib colormap name. Default 'nipy_spectral'.

  • show_stats_table (bool, optional) – If True (default), display the combined statistics table after the figure using IPython.display (or print as fallback). Set to False to suppress the table; the data is still computed and stored in stats_table.

Returns:

  • fig (matplotlib.figure.Figure)

  • axes (ndarray of matplotlib.axes.Axes)

  • Side-effects

  • ————

  • Sets stats_table — {prop_name: pandas.DataFrame} where

  • each DataFrame has columns

  • ['tslice', 'n', 'mean', 'std', 'CI_lower_95', 'CI_upper_95', 'peak_max'].

  • The full combined table is also printed to stdout.

Examples

>>> fig, axes = cntr.plot_temporal_distributions(
...     props=['area', 'aspect_ratio'],
...     ncols=2,
...     cmap='nipy_spectral',
... )
>>> import matplotlib.pyplot as plt
>>> plt.show()
indb
gsset
mctimeStart
mctimeStep
mctimeEnd
char_kwargs
stats_table