Configuration Overview

Hedgehog uses a hierarchical YAML configuration system. The main config file (config.yml) controls global settings and references separate per-stage config files. Each pipeline stage reads its own configuration independently, making it easy to tune individual stages without touching the rest.

Config File Hierarchy

config.yml                         # Global settings
  ├── config_mol_prep.yml          # Molecule preprocessing 
  ├── config_descriptors.yml       # Physicochemical descriptor calculation
  ├── config_structFilters.yml     # Structural filters
  ├── config_synthesis.yml         # Synthesis evaluation
  ├── config_docking.yml           # Molecular docking with SMINA, GNINA, and Matcha
  ├── config_docking_filters.yml   # Post-docking pose filters
  └── config_moleval.yml           # Generative metrics and reporting

How Configs Are Loaded

The CLI resolves the default config path relative to the installed package:

DEFAULT_CONFIG_PATH = str(Path(__file__).resolve().parent / "configs" / "config.yml")

You can override the master config path at runtime with --config/-c:

uv run hedgehog --config path/to/config.yml

Filesystem paths in the master config are resolved in this order:

1. absolute paths are used as-is
2. relative to the master config file location
3. relative to the source root for bundled src/hedgehog/... paths
4. relative to the current working directory as a final fallback

For example:

# Absolute — used as-is
config_descriptors: /opt/hedgehog/configs/config_descriptors.yml
 
# Relative to the master config file when that file lives beside configs/
config_descriptors: config_descriptors.yml
 
# Bundled source-checkout path
config_descriptors: src/hedgehog/configs/config_descriptors.yml
 

Overriding Parameters

There are three common ways to customise the pipeline:

1. Create your own config files and pass them via --config. Copy the default configs, edit them, then run:

   uv run hedgehog --config path/to/my_config.yml

2. Override common paths via CLI flags. Use:

   • --mols/-m to override generated_mols_path
   • --out/-o to override folder_to_save

3. For quick experiments in a source checkout, edit copied config files. If installed via PyPi do not edit configs inside an installed package in site-packages; copy them into your project directory and pass the copied master config with --config.

uv run hedgehog --config my_config.yml

Config Files