Installation and compatibility¶

numgeo-ACT is distributed as source code. It launches the numgeo executable for every element test; the executable supplied and tested with the same ACT release must therefore be available on the system PATH.

Supported release matrix¶

Other Python versions, Linux distributions or numgeo builds may work, but are not part of the verified ACT 0.1.0 matrix. Windows Python tests pass; the complete Windows calibration workflow is not supported until the native solver gate above is resolved.

The object identifiers above pin the exact solver binaries in addition to the release tag. Create v0.1.0 only from the merged release commit and ensure both objects are present in that tag.

Required Python packages¶

The supported optimisers and reporting workflow use the same compact scientific Python stack:

numpy
scipy
pandas
openpyxl
matplotlib
cycler
Pillow

DEEM, the SMAC-style optimiser and the local pattern search are included in the repository. They do not download code or models at run time. The SMAC-style optimiser can use scikit-learn when it is already installed, but its bundled NumPy Gaussian-process surrogate is used when scikit-learn is unavailable.

Windows (Python layer only; solver release blocked)¶

Open PowerShell in the directory in which you want to keep ACT:

git clone --branch v0.1.0 --depth 1 https://github.com/j-machacek/numgeo-ACT.git
Set-Location numgeo-ACT
py -3.12 -m venv .venv
.venv\Scripts\python -m pip install --upgrade pip
.venv\Scripts\python -m pip install -e .

The editable installation makes ACT importable while keeping the checked-out source as the code that runs. To enable the optional scikit-learn surrogate, use .venv\Scripts\python -m pip install -e ".[surrogate]" instead.

If Git is unavailable, download the release archive on GitHub, extract it and open PowerShell in the extracted directory before creating the environment.

The ACT v0.1.0 tag and the authorised replacement executable must form one tested release unit. Do not substitute an executable from main or another tag. After the release owner closes the native-solver gate, add the directory containing numgeo.exe, numgeo.bat or numgeo.cmd to the user or system PATH. A new terminal is normally required after changing PATH.

where.exe numgeo
.venv\Scripts\python -c "from ACT.utilities.runtime import get_numgeo_command; print(get_numgeo_command())"

Both commands must print the intended executable. This verifies discovery only; it does not close the Windows native-solver gate described above.

Linux¶

From a terminal:

git clone --branch v0.1.0 --depth 1 https://github.com/j-machacek/numgeo-ACT.git
cd numgeo-ACT
sudo apt-get update
sudo apt-get install --yes --no-install-recommends libopenblas0-serial
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e .

Use .venv/bin/python -m pip install -e ".[surrogate]" if the optional scikit-learn backend is wanted.

Use the Linux executable committed in the same v0.1.0 tag. Do not replace it with one from main or another tag. Add its directory to PATH and ensure that the executable bit is set:

chmod +x /path/to/numgeo
export PATH="/path/to:$PATH"
command -v numgeo
.venv/bin/python -c "from ACT.utilities.runtime import get_numgeo_command; print(get_numgeo_command())"

Put the export line in the appropriate shell profile if it should persist.

From the repository root, verify the pinned blob, native process and finite solver output with a new or empty work directory:

.venv/bin/python tests/run_numgeo_smoke.py --workdir numgeo-smoke

The validated Ubuntu 24.04 CI run produces 155 finite rows and reaches the requested 200 kPa load. The smoke test refuses to reuse a non-empty work directory so stale output cannot create a false pass.

Installation on a restricted computer¶

No optimiser repository needs to be cloned or installed separately. If the target computer cannot access PyPI, download wheels on another computer with the same operating system, processor architecture and Python version:

python -m pip download --only-binary=:all: --dest act-wheels \
  pip setuptools wheel numpy scipy pandas openpyxl matplotlib cycler Pillow

Copy the complete ACT release directory, the matching numgeo executable and the act-wheels directory to the restricted computer. Then install without network access:

python -m pip install --no-index --find-links=act-wheels --upgrade \
  pip setuptools wheel
python -m pip install --no-index --find-links=act-wheels \
  numpy scipy pandas openpyxl matplotlib cycler Pillow
python -m pip install --no-deps --no-build-isolation -e .

Upgrading pip from the wheel bundle is required because editable installs from pyproject.toml use PEP 660, supported by pip 21.3 and newer. Using a wheel set prepared for a different Python or platform is a common cause of installation failure.

The wheel directory covers Python packages only. For Ubuntu 24.04, stage libopenblas0-serial and its operating-system dependencies through an approved offline apt repository or a complete architecture-matched .deb bundle. The current release candidate does not provide a supported offline Windows solver bundle.

Import smoke test¶

Run this with the environment's Python interpreter:

python -c "from ACT import CMAES, DEEM, SMAC, local; from ACT.models import hardening_soil; from ACT.utilities.excel import excel; print('numgeo-ACT imports: OK')"

Then verify the solver lookup:

python -c "from ACT.utilities.runtime import get_numgeo_command; print(get_numgeo_command())"

These checks do not run a finite-element analysis. Before committing to a long calibration, use the simulation-only pass described in the Quickstart.

If a check fails, continue with Troubleshooting.