Key Concepts

Key Concepts

This page defines the core ideas and data structures used throughout UPXO. Read it before the generation, characterisation, or meshing pages if the API feels opaque.

---

Two families of grain structure generation

Family	Name	Idea	Physics of growth?
MCGS	Monte Carlo grain structure	Potts model on a lattice of spins	Yes — grains coarsen over time
VTGS	Voronoi tessellation grain structure	Partition space by nearest seed	No — instant geometry

MCGS — Each lattice site holds a spin (orientation index). Sites flip under a Boltzmann rule that favours fewer unlike-spin neighbours, so boundaries shrink. Available in 2D and 3D via the same class upxo.ggrowth.mcgs.mcgs; dimensionality comes from the Excel dashboard (dim), not from a separate 3D class.

VTGS — Seed points are placed in a domain; every location belongs to the nearest seed. Grains are convex (straight boundaries in 2D, planar facets in 3D). Classes: gtess2d, gtess3d.

Most new users start with MCGS2D and gsgen/monte_carlo_2d_01.ipynb. Details: 2D / 3D Grain Structure Generation.

---

The Potts model (MCGS)

1. Initialise — Random spin in 1 … Q on every lattice site.
2. Iterate — Propose a spin change; accept with probability related to energy change ΔE and temperature (min(1, exp(−ΔE/kT))). Energy falls when unlike-spin neighbour pairs decrease.
3. Time — One Monte Carlo Step (MCS) is on the order of N attempted flips for N sites. Mean grain size grows with MCS.

Important knobs (dashboard / uisim / uigrid):

Symbol / name	Meaning
Q	Number of allowed spin states
kT / temperature	Acceptance of unfavourable flips
Domain	Lattice extent and spacing (xmin…, dim)
mcalg	Which numerical kernel (e.g. 200/201/202 in 2D; 300a/300b/301/302 in 3D)
Save intervals	Which MCS values become time slices

---

Time slices (tslice / gsid)

One MCGS run can store many saved MCS values. Each saved state is a time slice.

Name	Meaning
MCS	Simulation time (Monte Carlo steps)
pxt.m	List of saved MCS indices for this run
tslice / gsid	Key into pxt.gs — a saved MCS value (or index into that history, depending on how the run was configured)
pxt.gs[tslice]	Grain structure object for that slice

from upxo.ggrowth.mcgs import mcgs

pxt = mcgs(input_dashboard='path/to/input_dashboard.xls')
pxt.simulate()
pxt.detect_grains()

tslice = pxt.m[-1]      # last saved MCS
gs = pxt.gs[tslice]
print(gs.n, gs.lgi.shape)  # attribute still named lgi in many objects — see LFI note below

Comparing several time slices is how you study grain-growth kinetics (size, morphology, topology vs MCS).

---

Labelled feature image (LFI)

The fundamental spatial representation of a grain structure is a 2D or 3D integer NumPy array: each pixel/voxel holds the ID of the feature (usually a grain) that owns it. The canonical name going forward is LFI / lfi (labelled feature image).

[ 1  1  1  2  2 ]
[ 1  1  2  2  2 ]   ← values are feature / grain IDs
[ 1  3  3  2  2 ]
[ 3  3  3  4  4 ]
[ 3  3  4  4  4 ]

Naming: use LFI; treat lgi as deprecated

You will still see several names in code and notebooks for the same kind of integer label field. Prefer lfi / LFI in new code and docs.

Name	Expansion	Status / notes
lfi / LFI	Labelled feature image	Canonical — carry this forward
lgi	Labelled grain image	Deprecated. Still appears widely (e.g. gs.lgi on MCGS time-slice objects) for historical reasons. Do not introduce new public APIs under this name; migrate call sites to LFI when practical.
cfi	Cell feature index	Used in some geometry / cell-oriented paths for a label field indexed by cell (feature) IDs
Other case-by-case names	e.g. feature maps in hierarchical or twin pipelines	Same concept: integer array mapping space → feature ID

Related fields (not the same as LFI)

Field	Role
pxt.S	Raw MC spin field (before / independent of feature labelling)
LFI after detect_grains	Feature (grain) IDs from connected-component labelling — often still stored as gs.lgi until renamed

Special labels in some pipelines (e.g. EBSD): 0 non-indexed / background; negative codes for boundary remnants or grains below a size threshold — see Data I/O.

---

The polycrystal object (pxt)

Conventionally named pxt, this is the top-level object from an MCGS run (mcgs instance). It is also a grid / simulation container, not only “geometry”.

Typical attributes:

Attribute	Meaning
pxt.S	Current spin field
pxt.m	Saved time-slice keys
pxt.gs	Dict of grain structures by time slice
pxt.uigrid, pxt.uisim, …	Parsed dashboard blocks

gs = pxt.gs[pxt.m[-1]]
print(gs.n)           # grain count after detect_grains
print(gs.lgi.shape)   # LFI shape (attribute name lgi is deprecated; see above)

---

Grain structure objects (time-slice classes)

After detect_grains(), each time slice is a dedicated class:

Dimension	Class	Module
2D	mcgs2_grain_structure	upxo.pxtal.mcgs2_temporal_slice
3D	mcgs3_grain_structure	upxo.pxtal.mcgs3_temporal_slice

Common ideas:

Capability	Typical API (2D)
Label field (LFI)	Often still gs.lgi in current objects (deprecated attribute name; concept = LFI)
Grain count	gs.n
Morphology	gs.char_morph_2d(...) → gs.prop (pandas DataFrame)
Neighbours	gs.find_neigh(...) → gs.neigh_gid
Export helpers	e.g. export_ctf, export_vtk2d (2D); export_vtk3d (3D)

Order of operations (MCGS): simulate() → detect_grains() → then characterisation (char_morph_2d / 3D morphology methods). Detection builds the LFI; characterisation fills property tables.

Voronoi objects (gtess2d / gtess3d) use a different surface (instances, seeds, cells) but still feed LFI or geometric representations into meshing and hierarchical pipelines.

---

Grain IDs (gid / fid)

Term	Meaning
gid	Grain ID — usual name in grain-structure APIs
fid	Feature ID — same idea in lower-level / multi-feature code

• IDs are typically 1-based after connected-component labelling.
• 0 is background / unlabelled and is excluded from per-grain property loops.
• IDs can be renumbered or merged by cleanup (gid_ops, smoothing, twin carving, FM hierarchy renames).

---

Excel dashboard (control surface for MCGS)

MCGS is controlled by an Excel input dashboard (.xls), not a long Python config. load_uidata / mcgs(input_dashboard=...) parse key/value rows into blocks such as:

Block	Role
uigrid	Domain, spacing, dim
uisim	Q, MCS, algorithm, temperature-related settings
uigsc	Grain characterisation preferences
uiint	Save / interval triggers
uigsprop, uigeorep, uimesh	Properties, geometry flags, mesh prefs

Templates live under src/upxo/interfaces/user_inputs/. See Data I/O.

---

Downstream structures (specialised pipelines)

These start from a base LFI (MCGS, Voronoi, or import) and add hierarchy or twins:

Pipeline	Concept	Entry
FM steel	PAG → packet → block → sub-block (KS)	FMSteel3DBase.from_lfi — FM Steels
Twinned FCC	Host grains → Σ3 primary/secondary twins	TwinnedSimple3DBase — CuCrZr & OFHC-Cu

Both still revolve around a 3D label field plus orientations and (for export) element sets.

---

Physical size vs lattice size

Concept	Meaning
Lattice / grid	Integer pixel or voxel indices (nx × ny [× nz])
Physical dimensions	Real lengths (e.g. µm) attached when building FE meshes, FM from_lfi(..., physical_dimensions=...), or twin voxel_size
Voxel/pixel size	Physical edge length per cell

Always know whether a quantity is in pixels/voxels or physical units before comparing to EBSD (step_size in microns).

---

Modules at a glance

Module / area	Purpose
upxo.ggrowth.mcgs	MCGS simulation + detect_grains
upxo.pxtal.mcgs2_temporal_slice / mcgs3_temporal_slice	Per-slice GS classes
upxo.pxtal.vortess2d / vortess3d	VTGS (gtess2d / gtess3d)
upxo.gsdataops.gid_ops	Grain-ID queries (small/boundary grains, merges, …)
upxo.gsdataops.grid_ops	Resample, rescale, section 3D → 2D
upxo.pxtalops	Smoothing, splits, other GS edits
upxo.viz.gsviz	Maps and PyVista grids
upxo.meshing	Conformal / non-conformal FE meshes
upxo.interfaces.user_inputs	Dashboards
upxo.interfaces.defdap	EBSD import
upxo.pxtal.fm_steel_3d / twinned_simple_3d	Hierarchical / twin pipelines + Abaqus export

Full API: Sphinx docs.

---

Mental model (one picture)

Excel dashboard
      │
      ▼
   mcgs.simulate()  ──►  spin field pxt.S  (MCS history)
      │
      ▼
   detect_grains()  ──►  LFI  (often still stored as gs.lgi — deprecated name)
      │
      ├─► char_morph / neighbours / GB ops / representativeness
      ├─► viz (see_map, PyVista, …)
      ├─► mesh + Abaqus / VTK export
      └─► optional: FM hierarchy or twin pipeline on 3D LFI

Voronoi skips the Potts time history: seeds → cells → (optional) LFI / geometry → same downstream branches.

---

Next steps

Goal	Page
Install and first notebook	Getting Started
Run MCGS / Voronoi	2D / 3D Generation
Properties and topology	Grain Characterisation
Material pipelines	Use Cases