Quick Start¶

This guide walks you through running your first simulation using the included example project (Lysozyme on a silica nanoparticle).

Prerequisites¶

Make sure AdsPro is installed and the environment is active:

source ~/adspro-venv/bin/activate

Run the Example¶

python -m adspro --project example

This runs a complete simulation for Lysozyme on a 71.3 nm silica NP at physiological conditions. Expect it to take several hours (most time is Phase 1 MD + umbrella sampling).

Progress is printed to the terminal. You will see:

[1/9] Coarse-graining protein: Lysozyme ...
[2/9] Detecting initial bonds ...
[3/9] Computing initial energy baseline ...
[4/9] Phase 0: Orientation screening (100 candidates) ...
[5/9] Phase 1: Langevin MD on 9 orientations ...
[6/9] Best orientation: #8 (E_morse = -91.8 kJ/mol)
[7/9] Phase 2: Umbrella sampling PMF (25 windows × 200,000 steps each) ...
  Smart scan: last Morse interaction at ξ=3.21 nm → window_max=5.90 nm
  Windows: 25  spacing=0.172 nm  σ=0.227 nm  overlap=1.32x  (good)
[8/9] WHAM: converged after 436 iterations
[9/9] Writing output files ...

View Results¶

Open the interactive 3D visualization in your browser:

projects/example/Lysozyme/adspro_result.html

For a text summary:

cat projects/example/Lysozyme/logs/summary_report.txt

The key line to look for:

ΔG_ads:  -28.76 kJ/mol
WHAM converged:  Yes

Setting Up Your Own Simulation¶

1. Create an input folder¶

AdsPro/
└── input/
    └── my_project/
        ├── config.yaml
        └── MyProtein.pdb

2. Get the PDB file¶

Download from AlphaFold (recommended) or RCSB PDB. AlphaFold structures work best since they provide a single, clean model.

3. Write config.yaml¶

Minimal configuration:

nanoparticle:
  radius:           71.3      # nm
  material:         silica
  zeta_potential:   -0.050    # V  (-50 mV)
  ionic_strength_mM: 20.0

simulation:
  temperature:      310.0     # K
  dt:               0.01      # ps
  max_steps:        100000
  n_orientations:   6
  n_workers:        4
  random_seed:      42
  n_runs:           1

pmf:
  v_pull_nm_ps:     0.01
  k_pull:           500.0
  steps_steered_md: 70000
  n_windows:        25
  k_window:         50.0
  steps_per_window: 200000
  steps_equil_window: 5000

proteins:
  - pdb_file: MyProtein.pdb
    ph:       7.4

4. Run¶

python -m adspro --project my_project

Command-Line Options¶

Option	Description
`--project NAME`	Project name. Reads from `input/<NAME>/config.yaml`
`--base-dir PATH`	Root directory of AdsPro (default: current directory)
`--log-level LEVEL`	`DEBUG`, `INFO`, `WARNING` (default), `ERROR`
`--output-format FORMAT`	`text` (default) or `json` (for SurfCo integration)

Multiple Proteins¶

To simulate several proteins against the same NP in one run:

proteins:
  - pdb_file: Lysozyme.pdb
    ph: 7.4
  - pdb_file: BSA.pdb
    ph: 7.4
  - pdb_file: Fibrinogen.pdb
    ph: 7.4

Each protein is processed sequentially. Results go to separate subdirectories:

projects/my_project/
├── Lysozyme/
├── BSA/
└── Fibrinogen/

Faster Exploratory Runs¶

For initial screening, reduce the PMF sampling:

simulation:
  max_steps:   10000
  n_runs:      1

pmf:
  n_windows:          15
  steps_per_window:   50000
  steps_equil_window: 2000

Warning

With reduced steps_per_window, WHAM may not converge (converged: false). Always use ≥ 200,000 steps/window for production results.

Debug Mode¶

To see detailed internal messages:

python -m adspro --project my_project --log-level DEBUG