Installation
One script, in a CPU mode or a GPU mode.
Prerequisites#
- Linux and Python 3.12 (Conda or uv)
- CUDA 12.8 drivers for training and for scoring language-model checkpoints
| Task | Hardware | Install |
|---|---|---|
| CPU quick start: build WOFOST scenarios, score scripted policies | CPU, about 1 GB disk | install.sh --cpu |
| Score a scripted policy or an NN baseline; train an NN baseline | CPU | install.sh --cpu |
| Score a language-model checkpoint on the test suite | one CUDA GPU | install.sh --gpu |
| Train a language-model policy (GRPO) | one or more CUDA GPUs | install.sh --gpu |
| Any DSSAT setting | Linux, GCC 11 with Fortran (or let Spack build it), a Spack path of at most 37 characters; 20–40 minutes to build on 16 cores, plus about 15 if Spack builds GCC | either mode + DSSAT runtime |
Install#
# 1. clone with the VeRL submodule git clone --recursive https://github.com/AgriManager-Framework/AgriManager.git cd AgriManager # 2. a clean Python 3.12 environment (Conda or uv) conda create -n agrimanager python=3.12 -y && conda activate agrimanager # or: uv venv --seed -p 3.12 .venv && source .venv/bin/activate # 3. one of the two modes bash install.sh --cpu # WOFOST + Cycles, scripted and NN baselines, tests bash install.sh --gpu # adds CUDA 12.8 PyTorch, vLLM and FlashAttention
What install.sh does#
- Initializes the VeRL submodule (v0.7.0-1, commit
7522bef0) and installs it. - Clones the WOFOST-Gym fork (
github.com/AgriManager-Framework/WOFOSTGym, commit253cf546) and the CycleGym fork, the Gym wrapper of the Cycles simulator (github.com/AgriManager-Framework/cyclesgym, commit2eb87583), into../AgriManagerExternal/and installs them. CycleGym's bootstrap downloads the Cyclesv0.12.9-alphabinary. Each fork is the upstream wrapper plus one patch commit. - Installs pinned Python packages:
--cpuusesrequirements/cpu.txtwithrequirements/locks/agrimanager-py312-cpu.lock.txt;--gpuusesrequirements/locks/agrimanager-py312-cu128.lock.txt(PyTorch 2.8.0, vLLM 0.11.0, Transformers 4.56.1) and a FlashAttention 2.8.1 wheel. - Installs AgriManager in editable mode and checks the imports.
Options: --external-dir DIR clones the wrappers elsewhere (then export
WOFOST_GYM_PATH and CYCLES_GYM_PATH); --skip-cycles leaves out CycleGym;
AGRI_USE_LOCKFILE=0 lets pip resolve versions, and results may then differ. DSSAT is a separate
native build: see DSSAT runtime.
On a shared cluster, create the environment on fast storage. On a hard-disk-backed parallel file system we
measured install.sh --gpu at 45 minutes and import vllm at about ten minutes; on an
NVMe-backed one, ten minutes and four seconds.
Weather data#
WOFOST weather pools download automatically on first use into .cache/wofost_gym/ at the repository
root, also when an evaluator scores a suite that needs them. If the repository sits on a small disk, make
.cache a symbolic link to a larger one first. Cycles and DSSAT need no download.
| Pool (Hugging Face) | Used by | Download | On disk |
|---|---|---|---|
AgriManager-Framework/weather_pool_maize | observation, action-menu, reward settings; WOFOST parts of Tier 3; quick start | 0.25 GB | about 0.95 GB |
AgriManager-Framework/wofost-weather-regime-pool | weather-regime training data | 0.29 GB | — |
AgriManager-Framework/wofost-weather-pool (20 crops) | crop-variety; the weather-regime and crop-variety test suites; WOFOST smoke tests | 17.6 GB | about 65 GB |
Environment variables#
Most users need none of these.
| Variable | Purpose |
|---|---|
WOFOST_GYM_REMOTE, WOFOST_GYM_REF | install: git remote and commit for WOFOST-Gym (default: the AgriManager-Framework fork at the pinned commit) |
CYCLES_GYM_REMOTE, CYCLES_GYM_REF | install: the same for CycleGym |
AGRI_EXTERNAL_DIR | install: same as --external-dir |
VLLM_USE_FLASHINFER_SAMPLER | GPU runs: the train and eval entry points set it to 0, so vLLM does not JIT-compile FlashInfer sampling kernels, which needs nvcc on the GPU node. Set 1 to use FlashInfer |
WOFOST_GYM_PATH, CYCLES_GYM_PATH, DSSAT_GYM_PATH | runtime: simulator locations (Configuration) |
HF_TOKEN | only to upload checkpoints or result bundles |
Check the install#
python -c "import agrimanager, pcse_gym, cyclesgym; print('ok')" bash smoke_tests/wofost_gym/run_cpu_quickstart.sh python -m pytest -q tests
Both modes were run on 2026-10-25 from a fresh clone with an empty pip cache: --cpu in about two
minutes on a CPU machine, --gpu in about ten minutes on one A40 (NVMe storage). In both, 194 tests
passed and the quick start printed the expected numbers. Per-simulator smoke tests are described in
smoke_tests/{wofost_gym,cycles_gym,gym_dssat}/README.md.