Monte Carlo Algorithms

Monte Carlo Algorithms

UPXO implements several Q-state Potts Monte Carlo kernels for grain growth. The dashboard field mcalg selects which module runs. Day-to-day use only needs the wired algorithms below; other files under algorithms/ are legacy, experimental, or unused by the current dispatcher.

Background: Key Concepts (Potts model). Control surface: Excel Input Dashboard. Pipelines: 2D / 3D Generation.

---

How selection works

mcgs(input_dashboard=...)
  → uisim.mcalg
  → simulate()
       dim == 2  →  start_algo2d_without_hops  →  alg200 / alg201 / alg202
       dim == 3  →  start_algo3d_without_hops  →  alg300a / alg300b / alg301 / alg302

Dispatch lives in upxo.ggrowth.mcgs (start_algo2d_without_hops, start_algo3d_without_hops).

Dimension	Accepted mcalg strings	Module
2D	'200', '200.0'	algorithms/alg200.py
2D	'201', '201.0'	algorithms/alg201.py
2D	'202', '202.0'	algorithms/alg202.py
3D	'300a'	algorithms/alg300a.py
3D	'300b'	algorithms/alg300b.py
3D	'301.0'	algorithms/alg301.py
3D	'302.0'	algorithms/alg302.py

Values are compared as strings (and for 2D, also '200.0'-style floats-as-strings from Excel).

Not implemented as a user path: multi-algorithm hops in 2D (start_algo2d_with_hops raises NotImplementedError). Prefer a single mcalg for the whole run.

---

2D algorithms (active)

All three use Numba-jitted neighbour loops over the spin field S, with append-index arrays (AIA0, AIA1) for periodic/wrapped indexing patterns, and write temporal grain-structure objects keyed by MCS.

ALG-200 — alg200

Item	Detail
Role	Baseline 2D Potts-style loop with non-locality matrix (NLM) weights on the 3×3 neighbourhood
Kernel	mcloop_alg200(cbp, sbp, S, AIA0, AIA1, NLM)
Energy	Neighbour agreement weighted by NLM entries; trial spin from unlike neighbours
Dashboard	mcalg = 200 (or 200.0)
Default in sweeps	parameter_sweep.__default_mcalg__ = '200'

Use when you want the classic NLM-weighted 2D kernel and compatibility with older demos/templates.

ALG-201 — alg201

Item	Detail
Role	2D variant that also accepts rsfso (second-order neighbour radius scale) from simulate(rsfso=…)
Entry	alg201.run(..., rsfso=rsfso, ...)
Dashboard	mcalg = 201
Templates	e.g. mcgs2d_100x100_m50_q10_mcalg201.xls

Prefer when demos or studies already pin algorithm 201 or need the rsfso hook exposed on the 2D path.

ALG-202 — alg202

Item	Detail
Role	Weighted neighbour energy path; console labels it “weighted (: ALG-202)”
Kernel	mcloop_alg202 — compares neighbour-count style DelH terms without the full NLM weighting of 200
Dashboard	mcalg = 202
Templates	e.g. input_dashboard_for_testing_50x50_alg202.xls

Useful for fast tests and for comparing weighted vs NLM-weighted kinetics.

Shared 2D plumbing

Input to run(...)	Meaning
S	Spin field
xgr, ygr, zgr	Grid coordinates
px_size	Pixel size
_a,_b,_c / NLM	Non-locality rows from build_NLM()
user_LIWM, LIWM	Optional local interaction weight matrix
uisim, uiint, uigrid, uidata	Dashboard blocks / intervals

Output: updated gs dict of temporal slices + fully_annealed status (can truncate save list if single-grain).

---

3D algorithms (active)

3D kernels operate on voxel spins with index arrays xinda, yinda, zinda, and use SciPy ndimage.label packaging via ndimg_label_pck where needed.

ALG-300a — alg300a

Item	Detail
Entry	mc_iterations_3d_alg300a
Dashboard	mcalg = 300a
Notes	First-line 3D variant “a”

ALG-300b — alg300b

Item	Detail
Entry	mc_iterations_3d_alg300b
Dashboard	mcalg = 300b
Notes	Parallel 3D variant “b” for comparative studies

ALG-301 — alg301

Item	Detail
Entry	mc_iterations_3d_alg301
Dashboard	mcalg = 301.0 (string form used in dispatch)

ALG-302 — alg302

Item	Detail
Entry	mc_iterations_3d_alg302
Dashboard	mcalg = 302.0
Extra	Uses rsfso from simulate(rsfso=…) (3D second-order scale; default in start_algo3d_without_hops is 3)

---

Other files under algorithms/ (not on the main dispatcher)

Present in the tree but not selected by the start_algo2d/3d_without_hops branches above:

Modules	Notes
alg200gen.py	Generator-related 200-family helper
alg220–alg224, alg230	Additional 2D-family experiments — wire yourself if needed
alg300.py, alg300_old.py	Older/alternate 300 paths
alg310.py (+ alg310_bu*)	Extended/backup 310 family

Do not set mcalg to these names expecting the stock mcgs.simulate() path to call them unless you extend the dispatcher.

---

Choosing an algorithm (practical)

Goal	Suggestion
First 2D tutorial	Match the demo dashboard (templates) — often 200/201/202 family
Fast 2D smoke test	Small grid + 202 test sheet
NLM-weighted baseline 2D	200
2D with rsfso knob	201
First 3D tutorial	Match demo_3d_*.xls mcalg
3D with rsfso	302.0
Algorithm sensitivity study	Parameter sweep

There is no automatic “best algorithm” ranking in UPXO — compare kinetics and morphology against your EBSD/target metrics.

---

Boltzmann / temperature (all algs)

Dashboard-driven (not algorithm-id-specific):

• consider_boltzmann_probability
• s_boltz_prob
• boltzmann_temp_factor_max
• NL (non-locality; 1 is the robust setting)
• boundary_condition_type
• S (number of states Q)
• mcsteps

See Excel Input Dashboard.

---

Source map

Path	Role
ggrowth/mcgs.py	Dispatch + NLM build + simulate
algorithms/alg200.py … alg202.py	Active 2D kernels
algorithms/alg300a.py … alg302.py	Active 3D kernels
pxtal/mcgs2_temporal_slice.py / mcgs3_temporal_slice.py	Time-slice GS objects written by kernels
tests/	Limited direct kernel coverage — most tests hit pipelines above MC

---

Status notes

• Kernels are performance-oriented Numba code with sparse formal math docs in-file; treat this page + papers as the conceptual layer.
• Algorithm “hops” across MCS windows are parsed into algo_hops but 2D multi-hop execution is not implemented.
• Changing mcalg mid-project without re-validating grain size vs MCS will change kinetics — keep dashboard + algorithm id with any published figure set.