Environment setup guide

This page is the complete setup guide for running Op3 on a fresh machine. Follow it top-to-bottom and you will have a working installation with all 140 V&V tests passing in under 30 minutes.

Supported platforms

Platform

Status

Notes

Windows 10 / 11 x64

primary

Development and V&V reference platform. All OpenFAST binaries are Windows x64.

Ubuntu 22.04 / 24.04 (WSL2 or native)

supported

OpenSeesPy + Python pipeline works; OpenFAST runs via Wine or a Linux build from source.

macOS 14+ (arm64 / x86_64)

experimental

OpenSeesPy works; OpenFAST requires source build.

Python prerequisites

Op3 requires Python 3.11 or 3.12. Python 3.13 is not yet supported (OpenSeesPy wheels have not been published).

python --version   # should print 3.11.x or 3.12.x

Core dependencies (from pyproject.toml):

numpy    >= 1.24
scipy    >= 1.11
pandas   >= 2.0
openseespy >= 3.5

Optional extras:

[test]  pytest >= 7,  pytest-cov >= 4
[docs]  sphinx >= 7,  alabaster
[dev]   mypy >= 1.5,  ruff >= 0.1

Step 1 — Clone the repository

git clone https://github.com/ksk5429/numerical_model.git
cd numerical_model

Step 2 — Create a Python environment

# Windows (PowerShell or Git Bash):
python -m venv .venv
source .venv/Scripts/activate

# Linux / macOS:
python -m venv .venv
source .venv/bin/activate

pip install --upgrade pip

Step 3 — Install Op3

pip install -e ".[test,docs]"

This installs the op3 package in editable mode with the pytest, pytest-cov, sphinx, and alabaster extras. The editable install means changes to op3/*.py files take effect immediately without a re-install step.

Step 4 — Bootstrap the OpenFAST v5.0.0 binary

Op3 exercises end-to-end coupled wind turbine simulation through the OpenFAST v5.0.0 binary. The binary is not bundled in the repository (it is 44 MB and tracked in .gitignore). Download it once into tools/openfast/:

mkdir -p tools/openfast
curl -L -o tools/openfast/OpenFAST.exe \
  https://github.com/OpenFAST/openfast/releases/download/v5.0.0/OpenFAST.exe

# Verify it runs:
tools/openfast/OpenFAST.exe -v
# Expected output: OpenFAST-v5.0.0

Alternatively, set OPENFAST_BIN to point at an existing install:

export OPENFAST_BIN="C:/path/to/OpenFAST.exe"

Op3’s runner checks the following locations in order:

  1. --binary CLI flag

  2. OPENFAST_BIN environment variable

  3. tools/openfast/OpenFAST.exe (v5 first)

  4. tools/openfast/openfast_x64.exe (v4 fallback)

  5. openfast / openfast_x64 on PATH

  6. C:\\openfast\\*, C:\\Program Files\\OpenFAST\\*, /usr/local/bin/openfast, /usr/bin/openfast

Step 5 — Bootstrap the r-test directory

Op3’s end-to-end OpenFAST runs depend on the canonical NREL r-test v5.0.0 templates (the OC3 Tripod deck and the shared 5MW_Baseline directory containing the Bladed DISCON.dll controller, airfoil polars, etc.). Clone it once:

mkdir -p tools/r-test_v5
cd tools/r-test_v5
git clone --depth=1 --branch v5.0.0 https://github.com/OpenFAST/r-test.git
cd ../..

Step 6 — Run the V&V suite

PYTHONUTF8=1 python scripts/release_validation_report.py

Expected output:

18/19 PASS  |  0 FAIL  |  1 optional  |  ~42 s total

The single optional failure is the SiteA 1P resonance flag on DNV-ST-0126 audit – this is a documented real engineering finding, not a software bug. See Verification & Validation for the full explanation.

Quick smoke test

If release_validation_report.py passes, you are done. For a 3-second sanity check instead:

from op3 import build_foundation, compose_tower_model
model = compose_tower_model(
    rotor="nrel_5mw_baseline",
    tower="nrel_5mw_oc3_tower",
    foundation=build_foundation(mode="fixed"),
)
print(f"f1 = {model.eigen(n_modes=3)[0]:.4f} Hz")
# Expected: f1 = 0.3158 Hz  (NREL/TP-500-38060 reference: 0.324 Hz)

Troubleshooting

OpenSeesPy import fails with a DLL load error on Windows

Install Microsoft Visual C++ Redistributable 2019+ from https://aka.ms/vs/17/release/vc_redist.x64.exe. OpenSeesPy is linked against MSVCRT and will not load without it.

OpenSeesPy eigen crashes with WARNING: symbolic analysis returns -8

Your domain has stale state from a previous build. Wrap your test in with op3._opensees_state.analysis("eigen"): or call ops.wipe() before the rebuild. The tests/conftest.py autouse fixture handles this automatically for pytest runs.

OpenFAST v5 rejects a SiteA v4 deck with Invalid numerical input

The v4 deck format differs from v5 (missing NRotors, CompSoil, MirrorRotor). Use the v5 deck under site_a_ref4mw/openfast_deck_v5/ instead.

Korean UTF-8 text prints as mojibake in stdout

Set PYTHONUTF8=1 before running any script. This enables Python UTF-8 mode globally and overrides the Windows cp949 default.

cython / scipy wheel fails to build

You are on an unsupported Python version (e.g. 3.13). Reinstall with Python 3.12: pyenv install 3.12.9 && pyenv local 3.12.9.

See Troubleshooting and FAQ for the complete FAQ.

Next steps