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. PointPYTHONPATHat a source checkout:export PYTHONPATH=/path/to/ws3
Without it, importing
ws3stops immediately with aWS3Error(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-runagainst a canonical femic bridge). The writer is imported from the femic source tree, resolved via theFEMIC_SRCenvironment 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_SRCanywhere else. Ensemble worker processes are spawned (not forked) and inheritPYTHONPATH, so export both variables in the shell that launches an ensemble.- Model inputs
The raw VRI polygon layer (
WL_VFSL.csv, referenced byinputs.wl_vfsl_pathin the ingestion config) and the validated femic TSA29 WS3 bridge package (referenced bybridge_path, with the femic stage-1 Woodstock CSVs as siblings of the canonical bridge) live outside this repository. The example configs inexamples/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.