Skip to content

FAQ

Jump to bottom
Sunil Anandatheertha edited this page Oct 6, 2026 · 8 revisions

FAQ & Troubleshooting

Short answers to common install, runtime, and “why doesn’t this work?” questions. For concepts (LFI, time slices, pxt), see Key Concepts. For package lists, see Dependencies.

Installation and environment

What Python version do I need?

Python ≥ 3.13 (requires-python in the package). Python 3.14 is also tested. On 3.12 or older pip stops with "requires a different Python".

Which OS is supported?

  • Windows is what the development team tests day to day (including full local pytest with PyVista/VTK).
  • Linux x86_64 runs the test suite in CI (Ubuntu, Python 3.13) without OpenGL/VTK-heavy paths.
  • Linux aarch64 (ARM): gmsh has no wheel, so pip install upxo[mesh] and upxo[all] fail there. pip install upxo, upxo[viz] and upxo[ebsd] work.
  • macOS was not run. Every dependency has a wheel for macOS arm64 and x86_64.

The PyPI classifier says “OS Independent,” but treat Windows as the reference platform.

How do I install UPXO?

pip install upxo

Optional extras:

Extra When you need it
upxo[ebsd] DefDAP EBSD import (.ctf / .crc)
upxo[mesh] tetgen / gmsh stack for some mesh paths
upxo[viz] Plotly only — not required for matplotlib/PyVista
upxo[all] All of the above

Developer / editable:

git clone https://github.com/Design-By-Fundamentals-UKAEA/UPXO.git
cd UPXO
pip install -e .
# or: pip install -e ".[all]"

import upxo fails or version looks wrong

  1. Confirm the active interpreter: python -c "import sys; print(sys.executable, sys.version)"
  2. Confirm install: python -c "import upxo; print(upxo.__version__)"
  3. If you use multiple envs (conda + venv + IDE), the notebook kernel may not match the shell where you pip installed.
  4. For editable installs, ensure you cloned the repo and installed from its root (pip install -e .).

Install fails with "No such file or directory" and a very long path (Windows)

Windows limits paths to 260 characters unless long paths are enabled. A file inside the jedi dependency has a long name, so an environment whose site-packages path is about 150 characters or more fails. Create the environment in a shorter path (for example C:\envs\upxo) or enable Windows long paths.

Where do pipelines write their output?

A pip-installed UPXO writes reports, raw exports and Abaqus files under ./data in the working directory. A source checkout writes to <checkout>/data.

netlsd is built from source during the install

netlsd is published only as a source distribution. pip builds it automatically. With --no-build-isolation, install setuptools first.

Numba, SciPy, or wheel build errors on install

Use a clean 3.13 venv, upgrade pip, then reinstall:

python -m pip install -U pip setuptools wheel
pip install upxo

If a dependency fails to build from source, prefer official wheels for your platform or a conda-forge stack for binary-heavy packages, then pip install upxo into that env.

Demos and data files

Where are the demo notebooks?

Not in the pip package. Clone the repository:

git clone https://github.com/Design-By-Fundamentals-UKAEA/UPXO.git --depth=1

Notebooks are in the separate UPXO-demos repository (e.g. gsgen/monte_carlo_2d_01.ipynb). Start there after install — see Getting Started.

Excel dashboard file not found / xlrd errors

MCGS expects a path to a real .xls dashboard:

pxt = mcgs(input_dashboard=r'C:\full\path\to\input_dashboard.xls')
  • Templates ship under src/upxo/interfaces/user_inputs/ in the git clone (and as package data when installed).
  • Relative paths depend on the process working directory (notebook cwd ≠ repo root is a common failure). Use an absolute path while debugging.
  • Classic dashboards use xlrd (.xls). Saving as .xlsx only and pointing mcgs at it may not work with the current load_uidata path.

Demo dashboard next to a notebook

Some notebooks pair with a local .xls dashboard. Open the notebook from that folder or set input_dashboard to the full path of that file.

Runtime: Monte Carlo and grain structures

2D vs 3D — which class?

There is one main MCGS class: from upxo.ggrowth.mcgs import mcgs.
Set dim in the Excel dashboard (2 or 3). Do not look for a separate mcgs3d class for the standard pipeline.

detect_grains / empty or wrong grain counts

Typical order:

mcgs(...) → simulate() → detect_grains() → then char_morph / export

If you characterise or plot before detect_grains(), the LFI may be missing or stale. After detection, properties come from char_morph_2d (2D) or the 3D morphology APIs — see Key Concepts.

Simulation is very slow

  • Domain size and MCS count dominate cost (especially 3D).
  • Start with small dashboards (demo_3d_06_20x20x20…, 50×50 2D test sheets).
  • Algorithm choice (mcalg 200/201/202 or 300a/300b/…) and Q also matter.
  • First Numba call can JIT-compile and look “stuck”; later runs are faster.

Algorithm hops / multi-algorithm sequences fail

Multi-algorithm “hops” in the dashboard are not a fully supported 2D path (start_algo2d_with_hops is not implemented). Prefer a single mcalg for production runs. See generation wiki pages.

Naming: LFI vs lgi

Why do docs say LFI but code says gs.lgi?

  • Canonical name going forward: LFI / lfi (labelled feature image).
  • lgi (labelled grain image) is deprecated but still used on many objects (gs.lgi).
  • Other historical/case names include cfi (cell feature index).

New code and docs should prefer LFI. Details: Key Concepts.

EBSD

DefDAP / EBSD import fails

  1. Install the extra: pip install upxo[ebsd] (pins defdap==0.93.6).
  2. Supported formats: Oxford .ctf and .crc via EBSDReader — not a general “any CIF/HDF5” importer.
  3. DefDAP often wants the path without forcing a double extension; follow EBSDReader.from_file / load docs.
  4. Without DefDAP installed, import errors are expected at first EBSD use.

See Data I/O.

Visualisation

PyVista / 3D plot does nothing or crashes

  • PyVista (VTK) is a core dependency; it needs a working OpenGL/display stack.
  • Headless Linux CI does not run full VTK paths; local Windows is the reference.
  • In Jupyter, ensure a backend that can show interactive widgets if you use notebook plotting.
  • For 2D, fall back to matplotlib / gsviz.see_map if 3D display is broken.

Is pip install upxo[viz] required for plots?

No for standard UPXO plots. Core includes matplotlib and PyVista.
[viz] only adds Plotly, which is not the main upxo.viz path today.

Meshing and export

gmsh / conformal mesh errors

3D conformal tet pipeline uses gmsh (and related stack). Install gmsh for your platform and ensure the Python gmsh module is importable. See Meshing.

Abaqus .inp won’t run as-is

Twin / FM / conformal exporters write partitioned INP files. 07_interactions and 08_steps_output (or equivalents) are often stubs — you must edit BCs, steps, and outputs before submitting a job. Warnings at export time are intentional. See Data I/O.

DAMASK / MOOSE / Dream.3D export

Package directories under interfaces/damask, moose, dream3d are empty stubs. Do not expect working exporters there. Use NumPy/VTK/Abaqus paths that are implemented.

HDF5 export

ArrExp2d can write .h5 / .hdf5 if h5py is installed. It is not a declared UPXO optional extra — install h5py yourself if needed.

Material pipelines (FM steel / twins)

FMSteelGenerator not found

Correct entry: FMSteel3DBase (chainable pipeline). See FM Steels.

Twin generation needs EBSD targets

Full twin insertion (introduce_primary_twins, etc.) is meant to be driven by measured twin thickness / volume fraction (and related) targets from EBSD workflows — not arbitrary placeholders. Use demos under. See CuCrZr & OFHC-Cu.

No calibrated Eurofer / OFHC parameter packs

UPXO does not ship alloy-specific calibrated dashboard packs for Eurofer97, F82H, T91, CuCrZr, or OFHC-Cu. You supply parameters from literature, EBSD, or internal calibration.

Testing and development

How do I run tests?

pytest tests/ -v
# headless subset (skip display-dependent tests):
pytest tests/ -v -m "not gui"

See Testing for CI vs Windows skips (VTK, display).

Where is the API reference?

Sphinx: https://design-by-fundamentals-ukaea.github.io/UPXO/

Licensing and support

Open source vs commercial

  • Default distribution: GPL-3.0 for open-source / academic use.
  • Commercial / proprietary use may need a separate licence — see repo COMMERCIAL.md / contact maintainers.

How do I get help or report a bug?

When filing a bug, include: OS, Python version, upxo.__version__, install method (pip / editable), minimal snippet, and full traceback.

How do I cite UPXO?

SoftwareX paper (see README / Home):

Anandatheertha et al., UKAEA Poly-XTAL operations (UPXO V1.0), SoftwareX 34 (2026) 102736. https://doi.org/10.1016/j.softx.2026.102736

Quick “still stuck?” checklist

  1. Python 3.13+ active?
  2. Installed into this interpreter?
  3. Using a git clone for demos/dashboards, not only pip?
  4. Absolute path to .xls dashboard?
  5. MCGS order: simulate → detect_grains → characterise?
  6. Right extra for EBSD/mesh (upxo[ebsd], etc.)?
  7. PyVista: real display / OpenGL available?
  8. Prefer LFI naming; ignore outdated lgi-only docs outside this wiki.

Still blocked → open a GitHub issue with environment + traceback.

Home | Getting Started | API Reference | PyPI | YouTube | GitHub

© 2026 UK Atomic Energy Authority (UKAEA) — GPL-3.0

UPXO Wiki

Home

Getting Started

Grain Structure Generation

Analysis & Operations

Output

Use Cases

Development

External

Clone this wiki locally