upxo.ggrowth.mcgsV1_1 module

mcgsV1_1 – a lean, GUI-driven Monte-Carlo grain-growth entry point for the 3D twinned-FCC pipeline (3D, algorithms 300a/300b only).

Built alongside – deliberately NOT replacing – upxo.ggrowth.mcgs.mcgs. That class is depended on by many other modules/notebooks and is not being touched here; this is a separate, additive module for the twinned_simple_3d GUI’s Monte-Carlo stage.

Why a new module instead of wiring the GUI straight to mcgs.mcgs

mcgs.mcgs reads its entire configuration from an Excel “input_dashboard” file through a multi-layer ingestion path (xlrd -> one flat dict -> 7 typed wrapper objects, one file each under upxo.interfaces.user_inputs). Of the dashboard’s ~141 rows, only a double-digit subset ever reaches the 3D algorithm functions (alg300a/alg300b); roughly 65 are read into the flat dict and simply discarded even inside mcgs.py itself. Wiring the GUI to that path would mean writing a throwaway Excel file on every run just to satisfy an xlrd read.

mcgsV1_1 builds the same flat dict directly from Python values (no Excel round-trip) and constructs the SAME wrapper classes mcgs.py uses (upxo.interfaces.user_inputs.uidata_mcgs_*), so the uigrid/uisim/uiint/ uimesh/uigsc/uigsprop/uigeorep objects built here remain attribute-compatible with mcgs3_temporal_slice.mcgs3_grain_structure and anything else in the codebase that expects a real instance of one of those classes – only the ingestion path changes, not the object shapes downstream code relies on.

It dispatches straight to the existing, unmodified upxo.algorithms.alg300a.mc_iterations_3d_alg300a / upxo.algorithms.alg300b.mc_iterations_3d_alg300b functions – the actual simulation core, already decoupled from mcgs.py’s Excel/wrapper machinery – so this module carries no duplicated physics, only argument construction.

Deliberately NOT built here (confirmed unused by the 3D algorithms while tracing this):

• Algorithm hopping – dead in mcgs.py itself: mcgs.simulate() always forces algo_hop=False right before checking it, and the “with hops” 3D functions are literally raise NotImplementedError.

• The non-locality matrix / NL / kineticity – mcgs.py’s initiate() builds this unconditionally for dim==3, but neither alg300a nor alg300b ever reads self.NLM/self.NLM_nd; they only take the appended-index arrays (xinda/yinda/zinda) below.

• The ~230-line hand-written face/edge/vertex block mcgs.py uses to build those appended-index arrays (mcgs.py ~600-839) – it gets unconditionally overwritten right after by a single np.pad(…, mode=’wrap’) call, so mcgsV1_1 just does the np.pad directly.

State-dependent Boltzmann acceptance (“q_related” mode)

mcgs.py’s own q_related formula derives a single automatic linear ramp across state indices from one scalar (boltzmann_temp_factor_max) – and its q_unrelated branch has a bug (mcgs.py:976, self.simpar.S does not exist; should be self.uisim.S) that crashes the first time it’s exercised.

mcgsV1_1 implements this fresh, correctly, and more flexibly: q_unrelated still takes one scalar temperature factor (uniform across all states); q_related takes Q independent per-state temperature factors, chosen by the user rather than auto-derived – letting some states grow faster/slower than others by direct design instead of a fixed ramp, e.g. to introduce natural multi-modality in the resulting grain-size distribution.

class upxo.ggrowth.mcgsV1_1.MCGSConfig(xmin: float, xmax: float, xinc: float, ymin: float, ymax: float, yinc: float, zmin: float, zmax: float, zinc: float, Q: int, mcalg: str, mcsteps: int, save_interval: int, consider_boltzmann: bool, boltzmann_mode: str = 'q_unrelated', boltzmann_temp_factor: float | None = None, boltzmann_temp_factors: Sequence[float] | None = None, print_interval: int = 10, rng_seed: int | None = None)

Bases: object

Everything mcgsV1_1 needs, in plain Python values – built directly from GUI shared_state, no Excel dashboard involved.

boltzmann_temp_factor is used when boltzmann_mode == ‘q_unrelated’ (one value shared by every state). boltzmann_temp_factors is used when boltzmann_mode == ‘q_related’ (one value per state, length must equal Q) – see the module docstring for why this replaced mcgs.py’s automatic single-factor ramp.

xmin: float

xmax: float

xinc: float

ymin: float

ymax: float

yinc: float

zmin: float

zmax: float

zinc: float

Q: int

mcalg: str

mcsteps: int

save_interval: int

consider_boltzmann: bool

boltzmann_mode: str = 'q_unrelated'

boltzmann_temp_factor: float | None = None

boltzmann_temp_factors: Sequence[float] | None = None

print_interval: int = 10

rng_seed: int | None = None

validate()

class upxo.ggrowth.mcgsV1_1.mcgsV1_1(config: MCGSConfig, verbose=True)

Bases: object

Lean 3D Monte-Carlo grain-growth driver. Usage mirrors mcgs.mcgs’s notebook usage pattern (pxt.simulate(); pxt.m[-1]; pxt.gs[tslice]) so it can be swapped in for GUI wiring without reshaping the rest of the twinned_simple_3d pipeline.

simulate(verbose=None)

Run the 3D Monte-Carlo grain-growth simulation and populate self.gs (temporal slice index -> mcgs3_grain_structure) and self.m (sorted list of the temporal slice indices that were saved).