Installation

fresh-salvage is not yet published to a package index, so install it from a source checkout into a repo-local virtual environment.

Requirements

  • Python 3.11 or newer (requires-python = ">=3.11"; CI tests 3.11 and 3.12). A system Python, pyenv, or conda base all work — only the version floor matters.

  • Git, to check out this repository and the two external source dependencies below. Both come from the FRESH ecosystem, the UBC forestry-research software family this package belongs to.

  • Enough cores and RAM for the workload you plan: the test suite and smoke profiles run on a laptop; the full-TSA production WS3 solve and large ensembles assume a workstation (the recorded benchmarks use a 64-core host).

Create The Environment

Linux and macOS:

python -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .[dev]

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .[dev]

The runtime dependencies (PyYAML, highspy, numpy, pandas, pyarrow, pydantic, rich, typer) install from PyPI with the package. The [dev] extra adds pytest, ruff, Sphinx, the RTD theme, build, and twine; narrower extras exist for focused work: [test] (pytest), [quality] (ruff), [docs] (Sphinx + theme), [release] (build + twine).

External Dependencies

Three inputs come from outside PyPI. We do not ship copies of them in this repository (they are never vendored; see the data-requirements section of the project README):

ws3 (wood supply model)

Required for ws3-run, rh-run, ensemble-run, and the WS3-dependent tests. Point PYTHONPATH at a source checkout:

export PYTHONPATH=/path/to/ws3

Without it, importing ws3 stops immediately with a WS3Error (ws3_import_failed) whose message names the expected resolution.

femic (WS3 bridge writer)

Required to rebuild the WS3 input files (the first ws3-run/rh-run/ensemble-run against a canonical femic bridge). The writer is imported from the femic source tree, resolved via the FEMIC_SRC environment variable with a configured default path as fallback:

export FEMIC_SRC=/path/to/femic/src

The configured default path is machine-specific to the FRESH lab host; set FEMIC_SRC anywhere else. Ensemble worker processes are spawned (not forked) and inherit PYTHONPATH, so export both variables in the shell that launches an ensemble.

Model inputs

The raw VRI polygon layer (WL_VFSL.csv, referenced by inputs.wl_vfsl_path in the ingestion config) and the validated femic TSA29 WS3 bridge package (referenced by bridge_path, with the femic stage-1 Woodstock CSVs as siblings of the canonical bridge) live outside this repository. The example configs in examples/ carry machine-specific absolute paths from the FRESH lab host — replace them with your own copies before running. Tracked tests and examples use synthetic or public-safe fixtures only.

Verify The Install

fresh-salvage --help
fresh-salvage --version        # fresh-salvage 0.1.0a1
python -m ruff check .
python -m pytest               # 203 tests (201 passed, 2 skipped unless
                               # the optional ws3 checkout is on PYTHONPATH)

WS3-dependent tests expect the ws3 checkout on PYTHONPATH; the end-to-end ensemble test additionally needs the local TSA29 inputs and skips with an explicit message when they are unavailable.

With the external dependencies in place, run the deterministic WS3 smoke profile as the pipeline-level verification gate:

fresh-salvage ws3-run examples/ws3_tsa29.yaml --smoke

The smoke profile solves a 3-period horizon on the full-TSA bridge (output under outputs/ws3_smoke); the recorded regression objective is 24,328,759.75 m3 (see Validation). All six pipeline commands (ingest, ws3-run, principal-run, agent-run, rh-run, ensemble-run) are implemented; see Quickstart for a first end-to-end run and Command Line for the full command reference.