Architecture

Architecture / Package Map

High-level map of the UPXO Python package (src/upxo/) for contributors and advanced users. This is not a substitute for the Sphinx API reference. Concepts: Key Concepts.

---

Packaging layout

UPXO/                          # git repository root
├── pyproject.toml             # package metadata, deps, extras
├── src/upxo/                  # importable package
├── tests/                     # pytest (repo root)
├── docs/                      # Sphinx
├── data/                      # large examples / sessions (often local)
└── admin/                     # private notes (typically gitignored)

Install mode: package-dir = {"" = "src"} → import upxo loads from src/upxo.

Version (example): see pyproject.toml / upxo.__version__.
Python: ≥ 3.13.

---

Layered mental model

┌─────────────────────────────────────────────────────────────┐
│  demos/  ·  scripts/  ·  Excel dashboards                   │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│  Domain pipelines                                           │
│  pxtal.fm_steel_3d  ·  pxtal.twinned_simple_3d  ·  repgen   │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│  Grain structure generation                                 │
│  ggrowth.mcgs  ·  pxtal.vortess2d/3d  ·  algorithms/*       │
│  pxtal.mcgs2/3_temporal_slice                               │
└───────────────────────────┬─────────────────────────────────┘
                            │  LFI / geometry
┌───────────────────────────▼─────────────────────────────────┐
│  Ops on labels & graphs                                     │
│  gsdataops  ·  pxtalops  ·  gbops  ·  netops  ·  propOps    │
│  charops  ·  imageOps  ·  topOps  ·  statops                │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌──────────────┬────────────▼────────────┬────────────────────┐
│ Crystallography │     Meshing/export    │   Visualisation    │
│ xtalphy · texOps│  meshing · exporters  │  viz/*             │
│ material.texture│  interfaces.io/abaqus │                    │
└──────────────┴─────────────────────────┴────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│  Support                                                    │
│  _sup  ·  interfaces.user_inputs  ·  interfaces.defdap      │
│  interfaces.os  ·  flags_and_controls                       │
└─────────────────────────────────────────────────────────────┘

---

Package directory map

Generation and time-slice objects

Path	Role
ggrowth/	mcgs Potts driver, make3d stack helpers
algorithms/	Numba MC kernels (2D 200–202, 3D 300a/b–302, …)
pxtal/mcgs2_temporal_slice.py	2D GS per MCS
pxtal/mcgs3_temporal_slice.py	3D GS per MCS
pxtal/vortess2d.py / vortess3d.py	gtess2d / gtess3d Voronoi
pxtal/gridops.py	Grid / intercept helpers on pxtals
parswep/	Multi-run parameter sweeps (research)

Specialised 3D pipelines

Path	Role
pxtal/fm_steel_3d/	FM hierarchy chain, mesh export, viz workers
pxtal/twinned_simple_3d/	Twin hosts, Σ3, clean, validate, Abaqus
repgen/	Rank MC time slices vs reference (2D/3D)
repqual/	Representativeness assessors (stats / networks)
surrModelOps/	Batch LFI dumps for surrogate datasets

Label / geometry / property ops

Path	Role
gsdataops/	gid_ops, grid_ops (section, resample)
pxtalops/	Smoothing, grain splitting, voxel↔geom bridges
gbops/	2D/3D GB detection, junction points, GB point sets
netops/	Neighbour graphs, degree / network comparison
propOps/	Volume/morph bulk helpers, ellipsoid fits
charops/	Feature characterisation entry (mchar)
imageOps/	Label reindex; voids stub
topOps/	Topology repair (e.g. non-manifold voxels)
statops/	Sampling, distributions
fdbOps/	Feature database entries
geoEntities/	Points, lines, rings, multipoints (2D/3D)
connops/	Neighbour finding helpers

Crystallography and materials

Path	Role
xtalphy/	Primary orientation math, MDF, CSL, twin roles
texOps/	FCCTexture synthetic rolling components
viz/xphy/	Pole figures
material/	Material identity, registry, processing route, texture profile
xtal/, xtalops/, mechanics/	Additional crystal / twin utilities

See Texture & Crystallography.

Meshing and I/O

Path	Role
meshing/	2D conformal/non-conformal, ABQ writers
meshing/gbconformant/d3v2p0/	Voxel-interface 3D tets (mesh_voxels, Gmsh remesh, C3D4 export)
interfaces/user_inputs/	Excel dashboards + load_uidata
interfaces/defdap/	EBSDReader
interfaces/io/	ArrExp2d multi-format array export
interfaces/os/	Paths, file helpers
interfaces/abaqus/	CAE-side script (runs inside Abaqus)
`interfaces/damask	moose
_sup/	Excel inout, CTF export (export_data), math, types

Visualisation and demos

Path	Role
viz/	gsviz, gbviz, meshviz, ebsdviz, vizDistr, …
UPXO-demos	Teaching and pipeline notebooks (not in pip wheel)
scripts/, tutorials/	Extra examples (dev-oriented)

Infrastructure

Path	Role
_sup/	Shared utilities
flags_and_controls/	Global flags
uiOps/	Output display helpers
profiling/, tests_and_benchMarks/	Performance / internal benches
external/	Vendored third-party snippets (e.g. ellipsoid fit)

---

Data contracts (cross-cutting)

Contract	Description
LFI	Integer array (2D/3D): space → feature id. Canonical name going forward; attribute lgi on some objects is deprecated.
Time slice	Saved MCS state in pxt.gs[key] after MCGS
Dashboard	Flat .xls key/value → uigrid/uisim/… blocks
Orientations	Per-grain or per-pixel Euler / quat / matrix
Abaqus export	Partitioned model_master.inp + includes (often stub steps)

---

Optional dependency boundaries

Extra	Touches
Core	NumPy stack, PyVista, xlrd, … — MC, most viz, dashboards
[ebsd]	DefDAP → interfaces.defdap
[mesh]	tetgen/gmsh — some Voronoi/mesh paths
[viz]	Plotly only (not primary upxo.viz)
External tools	gmsh, Abaqus CAE, h5py (HDF5 via ArrExp2d)

---

Where to change what

If you are changing…	Start in…
Potts kinetics / MC kernel	algorithms/, ggrowth/mcgs.py
Dashboard keys	interfaces/user_inputs/uidata_mcgs_*.py + templates
2D/3D GS properties	pxtal/mcgs*_temporal_slice.py, charops/, propOps/
FM hierarchy	pxtal/fm_steel_3d/
Twins	pxtal/twinned_simple_3d/
Conformal 3D mesh	meshing/gbconformant/d3v2p0/
Pole figures / MDF math	viz/xphy/, xtalphy/crystal_orientation.py
User wiki	UPXO.wiki repo (not this tree)
Tests	tests/ mirroring package areas

---

Related wiki pages

Page	Focus
Key Concepts	LFI, tslice, pxt
Contributing	Branches, CLA, tests
Testing	Coverage map
GB-conformant 3D	d3v2p0 voxel-interface tet pipeline
2D Grain Structure Geometrification	Label image → Shapely polygons, both techniques
Capability pages	Generation, meshing, I/O, use cases

---

Status notes

• Architecture is evolutionary: multiple generations of helpers coexist (orientation.py vs crystal_orientation.py, old mesher classes, empty FE interface packages). Prefer modules cited on current wiki pages for new work.
• Large binary/session trees under data/ are workflow artefacts, not part of the importable API.
• Sphinx may document more modules than are “supported user surface”; wiki capability pages are the curated story.