Excel Input Dashboard

Excel Input Dashboard

Monte Carlo grain structure (MCGS) runs in UPXO are controlled primarily by an Excel .xls dashboard: a single sheet of name / value pairs. The same mechanism feeds 2D and 3D simulations; dimensionality is a field in the file (dim), not a different Python class.

Related: Key Concepts, 2D / 3D Generation, Data I/O, FAQ.

---

How loading works

from upxo.ggrowth.mcgs import mcgs
from upxo.interfaces.user_inputs.gather_user_inputs import load_uidata

# Preferred day-to-day use
pxt = mcgs(input_dashboard=r'C:\path\to\input_dashboard.xls')

# Or inspect parsed blocks without running MC
uidata = load_uidata(r'C:\path\to\input_dashboard.xls')
# keys: uigrid, uisim, uigsc, uiint, uigsprop, uigeorep, uimesh

File format

Item	Behaviour
Engine	xlrd reads classic .xls
Layout	First sheet; column A = parameter name, column B = value
Path	Absolute paths work. Relative names are resolved relative to src/upxo/interfaces/user_inputs/ when loaded through the package helper (see gather_user_inputs._load_user_input_data_)

Do not assume a multi-sheet workbook layout for MCGS control — it is a flat key/value table. Saving only as .xlsx without a matching reader path is a common failure mode; keep .xls templates for MCGS.

---

Parsed blocks (load_uidata → mcgs)

Dict key	Class module	Role
uigrid	uidata_mcgs_gridding_definitions	Domain geometry and dim
uisim	uidata_mcgs_simpar	Q/states, MCS, algorithm, Boltzmann, BC, non-locality
uigsc	uidata_mcgs_grain_structure_characterisation	Grain-ID library prefs
uiint	uidata_mcgs_intervals	Save intervals, plot/display intervals
uigsprop	uidata_mcgs_property_calc	Which properties to compute (flags)
uigeorep	uidata_mcgs_generate_geom_reprs	Geometric representation flags
uimesh	uidata_mcgs_mesh	Mesh conformity / FE target prefs

On the live mcgs instance these appear as pxt.uigrid, pxt.uisim, etc.

---

Core keys (by block)

Names must match what the parsers read from column A (spelling is exact, including historical typos where present).

Grid — uigrid

Key	Meaning
type	Grid type string
dim	2 or 3 — selects 2D vs 3D MC path
xmin, xmax, xinc	X extent and spacing
ymin, ymax, yinc	Y extent and spacing
zmin, zmax, zinc	Z extent and spacing (used when dim=3; still present in 2D templates)
transformation	Geometric transformation flag for the grid

Large pixel counts can trip an internal lock (npixels_max default order 500×500 in the grid class) — use smaller domains for tests.

Simulation — uisim

Key	Meaning
S	Number of spin states (Q)
mcsteps	Total Monte Carlo steps
mcalg	Algorithm id string — 2D: 200 / 201 / 202; 3D: 300a / 300b / 301.0 / 302.0 (see generation pages)
state_sampling_scheme	How trial states are sampled
consider_boltzmann_probability	Use Boltzmann acceptance
s_boltz_prob	State-dependent Boltzmann mode
boltzmann_temp_factor_max	Temperature factor
boundary_condition_type	Boundary condition type
NL	Non-locality neighbourhood order (current code supports 1 robustly)
kineticity	Kineticity mode string

Algorithm hops: the parser builds algo_hops from mcalg. Multi-hop 2D switching is not implemented as a user path — use a single algorithm. See FAQ.

Intervals — uiint

Key	Meaning
mcint_save_at_mcstep_interval	How often to save time slices into pxt.gs
save_final_S_only	If true, prefer final state only
mcint_grain_size_par_estim	Interval for grain-size estimation hooks
mcint_gb_par_estimation	GB parameter estimation interval
mcint_grain_shape_par_estim	Shape estimation interval
mcint_promt_display	Prompt/display interval (historical spelling promt)
mcint_plot_grain_structure	Whether to plot during run

Saved MCS values become time slices (pxt.m, pxt.gs[...]) — Key Concepts.

Characterisation — uigsc

Key	Meaning
grain_identification_library	Library preference for grain ID (e.g. scikit-image / related options used by detection paths)

Much characterisation is still done after the run with detect_grains() and char_morph_* in Python; dashboard flags feed defaults where wired.

Property calculation — uigsprop

Boolean (and related) flags such as:

• compute_grain_area_pix, compute_grain_area_pol
• compute_gb_length_pol, compute_gb_length_pxl
• compute_grain_moments
• compute_grain_area_distr, _kde, _prop
• compute_gb_length_distr, _kde, _prop
• grain_area_type_to_consider, gb_length_type_to_consider

Exact set is defined in uidata_mcgs_property_calc.py — open a template .xls side by side when editing.

Geometry representations — uigeorep

Flags such as:

• make_mp_grain_centoids (historical spelling)
• make_mp_grain_points
• make_ring_grain_boundaries
• make_xtal_grain, make_chull_grain
• create_gbz

Mesh prefs — uimesh

Key	Meaning
mesh_gb_conformity	Conformant vs non-conformant intent
mesh_target_fe_software	Target FE package name
mesh_meshing_package	Mesher package preference
mesh_reduced_integration	Reduced integration flag
mesh_element_type	Element type string

Full meshing is often done later via upxo.meshing exporters rather than only from these flags.

---

Template files in the repo

Under src/upxo/interfaces/user_inputs/ (also packaged as data in installs when included):

File	Typical use
input_dashboard.xls	Default / general template
input_dashboardV1.xls	Variant template
mcgs2d_100x100_m50_q10_mcalg201.xls	Explicit 2D small study
input_dashboard_for_testing_50x50_alg202.xls	Fast 2D test
demo_3d_01.xls … demo_3d_05.xls	3D demos
demo_3d_06_20x20x20Q10M100.xls	Tiny 3D
demo_3d_06_100x100x100Q16M100.xls	Larger 3D
a_01.xls … a_09.xls	Additional study sheets
idash-rep_qual_*	Representativeness sample/target pairs
ConformalMeshing2D.xlsx	Meshing-related workbook (not the flat MCGS key/value path)

---

Recommended editing workflow

1. Copy a template close to your case (2D vs 3D) — do not edit the only pristine template in place if you share a clone.
2. Change dim, domain (xmin…zinc), S, mcsteps, mcalg, and save interval first.
3. Keep domains small until the pipeline runs (detect_grains + a plot).
4. Point mcgs(input_dashboard=...) at the absolute path of your copy.
5. After a successful run, tune Boltzmann / NL / property flags.

from upxo.ggrowth.mcgs import mcgs

pxt = mcgs(input_dashboard=r'C:\work\my_mcgs2d.xls')
pxt.simulate()
pxt.detect_grains()
gs = pxt.gs[pxt.m[-1]]
print(gs.n)

---

What dashboards do not control

Area	Controlled instead by
FM steel hierarchy (PAG/blocks/KS)	fm_steel_3d API
Twin host/TVF/thickness	twinned_simple_3d + EBSD
Voronoi seed sampling	gtess2d / gtess3d constructors (Python), not this MCGS sheet
Full conformal tet export options	d3v2p0 / exporters

---

Manual / notebook UI alternatives

• manual_uidata_mcgs_*.py — construct UI blocks in pure Python for parameter studies without Excel.
• nbWidgets.py — Jupyter widgets for twin/repr property selection (not a replacement for the full MCGS sheet).
• parswep — multi-run parameter sweep infrastructure (research).

---

Source map

Path	Role
interfaces/user_inputs/gather_user_inputs.py	load_uidata, xlrd reader
interfaces/user_inputs/uidata_mcgs_*.py	Per-block parsers
interfaces/user_inputs/*.xls	Templates
ggrowth/mcgs.py	Consumes dashboard via mcgs(input_dashboard=...)

---

Status notes

• Key names are string-exact and include historical spellings (promt, centoids) — copy from a working template rather than guessing.
• 3D requires consistent dim=3 and meaningful z* spacing.
• Prefer documented single mcalg values over multi-hop experiments.
• For alloy-specific twin/FM workflows, dashboards only build the base MC structure; hierarchy/twins are separate stages.