Skip to content

Configuration

How PCT jobs are configured, where files live, and how CLI flags map to runtime behavior.

Project layout

  • Source root: PCT/
  • Datasets: datasets/ (folders per run; see bin/dataset_optim_command.sh for examples)
  • Results: results/<model>/run_<timestamp>[_suffix]/ (loss plots, checkpoints, analysis, predicted params)
  • Scripts: bin/optimize_network.py, bin/optimize_params.py

Config sources and overrides

  • Primary configuration is via CLI flags.
  • Paths are resolved relative to the repo root unless absolute.
  • Validation occurs in the scripts (e.g., dataset existence, positive chunk sizes).
  • Env vars:
  • UV_CACHE_DIR: cache location for uv run
  • XLA_PYTHON_CLIENT_PREALLOCATE=false: avoid JAX preallocation (used in dataset_optim_command.sh)

Outputs and artifacts

  • Predicted params: --output (defaults inside the run directory for optimize_network; dataset folder for optimize_params)
  • Best model/params (with validation): --best-model-path, --best-params-output
  • Loss/analysis: loss curves (pct_network_loss.png/json), analysis plots under analysis/, optimizer/model checkpoints (pct_network_model.msgpack, pct_network_optimizer.msgpack)
  • optimize_params artifacts: tuned params JSON (pct_optimized_params.json), history plot (pct_optimization_history.png)

Logging

  • Weights & Biases: --wandb-project, --wandb-entity, --wandb-run-name, --wandb-tags, --wandb-mode
  • Note: to use WandB, install wandb (uv pip install wandb), set WANDB_API_KEY in the environment, and provide --wandb-project (and optionally --wandb-entity).
  • Console: scripts print per-epoch metrics and validation summaries; tqdm progress for training/optimization

Reproducibility

  • Seed all randomness via --seed
  • Fix environment (JAX/XLA version) via uv lock and uv sync
  • For deterministic GPU memory use, set XLA_PYTHON_CLIENT_PREALLOCATE=false as in dataset_optim_command.sh

Example (optimize_network)

UV_CACHE_DIR=.uv-cache-local XLA_PYTHON_CLIENT_PREALLOCATE=false \
uv run --project PCT python PCT/bin/optimize_network.py \
  --dataset datasets/june_training_data/train_redp_1 \
  --val-dataset datasets/whitef_june_17/whitef_default_1 \
  --epochs 50 --batch-size 512 --lr 1e-4 \
  --model singletrack-augmented --model-hidden 512 256 \
  --dataset-cache dataset_bundle.npz --val-dataset-cache val_dataset_bundle.npz \
  --curriculum-batches 1000 --curriculum-timesteps 5 \
  --output pct_predicted_params.json \
  --wandb-project pct-network-optim