Configuration Reference¶

All simulation parameters are set in a config.yaml file inside the input/<project>/ folder.

Complete Example¶

# AdsPro v0.1.0 Configuration File

nanoparticle:
  radius:              71.3      # nm — nanoparticle radius
  material:            silica    # surface material
  zeta_potential:      -0.050    # V — surface potential (-50 mV)
  ionic_strength_mM:   20.0      # mM NaCl → Debye length computed automatically
  surface_charge_mode: grahame   # 'grahame' (from zeta) or 'direct'

simulation:
  placement_distance:    0.5     # nm — gap between protein and NP at start
  temperature:           310.0   # K — physiological temperature (constant NVT)
  dt:                    0.01    # ps — time step
  max_steps:             100000  # steps per orientation in Phase 1
  equilibrium_window:    500
  equilibrium_threshold: 0.01    # kJ/mol — Phase 1 convergence tolerance

  n_orientations:        6       # number of top Phase-0 orientations for Phase 1
  orientation_selection: total_morse

  com_restraint_max_distance: auto
  com_restraint_k:            5000.0   # kJ/mol/nm² — COM restraint stiffness

  em_tol:       500.0     # kJ/mol/nm — energy minimization force tolerance
  em_step:      0.01      # nm — steepest-descent step size
  em_max_steps: 5000

  n_workers:   4
  random_seed: 42         # set to null for non-reproducible runs
  n_runs:      1          # number of independent simulations

pmf:
  v_pull_nm_ps:       0.01    # nm/ps — steered MD pulling velocity
  k_pull:             500.0   # kJ/mol/nm² — steered MD restraint stiffness
  steps_steered_md:   70000   # must cover full window range

  n_windows:          25      # umbrella windows along reaction coordinate
  k_window:           50.0    # kJ/mol/nm² — window harmonic bias
  steps_per_window:   200000  # sampling steps per window
  steps_equil_window: 5000    # equilibration steps before sampling each window

proteins:
  - pdb_file: Lysozyme.pdb
    ph:       7.4

Nanoparticle Section¶

Parameter	Type	Required	Description
`radius`	float	Yes	NP radius in nm
`material`	string	Yes	Surface material. Must match a key in `data/aa_parameters/`
`zeta_potential`	float	Yes	Surface potential in Volts. Negative for anionic surfaces (e.g., silica: −0.050 = −50 mV)
`ionic_strength_mM`	float	No (default: 20.0)	Salt concentration in mM → λ_D computed automatically
`surface_charge_mode`	string	No (default: `grahame`)	`grahame`: σ computed from ζ via Grahame equation. `direct`: user specifies σ directly
`sigma_direct_e_per_nm2`	float	Only if `direct`	Surface charge density in elementary charges per nm²
`lambda_D_nm`	float	No	Manual override of Debye length. Leave unset to compute from `ionic_strength_mM`

Simulation Section¶

Integration¶

Parameter	Type	Default	Description
`temperature`	float	310.0	Simulation temperature in K (NVT)
`dt`	float	0.01	Integration time step in ps. Must be ≤ 0.02 ps
`placement_distance`	float	0.5	Initial gap (nm) between protein surface and NP surface before Phase 1

Phase 1 Convergence¶

Parameter	Type	Default	Description
`max_steps`	int	5000	Phase 1 maximum MD steps per orientation
`equilibrium_window`	int	500	Steps over which to check energy convergence
`equilibrium_threshold`	float	0.01	Energy change tolerance for declaring convergence (kJ/mol)

Production vs. exploratory

For production runs: max_steps = 100000. For quick screening: max_steps = 10000. The protein typically reaches a stable adsorbed conformation within 20,000–50,000 steps.

Orientation Selection¶

Parameter	Type	Default	Description
`n_orientations`	int	4	Number of top Phase-0 orientations to refine in Phase 1
`orientation_selection`	string	`total_morse`	Scoring metric for Phase 0 ranking. `total_morse` is recommended

COM Restraint¶

Parameter	Type	Default	Description
`com_restraint_max_distance`	float or `auto`	`auto`	Maximum COM distance from NP surface (nm). `auto` = use initial placement distance
`com_restraint_k`	float	5000.0	COM restraint spring constant (kJ/mol/nm²)

Energy Minimization¶

Parameter	Type	Default	Description
`em_tol`	float	500.0	Target maximum force for energy minimization (kJ/mol/nm)
`em_step`	float	0.01	Steepest-descent step size (nm)
`em_max_steps`	int	5000	Maximum steepest-descent steps

Parallelism and Reproducibility¶

Parameter	Type	Default	Description
`n_workers`	int	4	CPU workers for parallel Phase 0 scoring
`random_seed`	int or null	null	Fixed seed for reproducibility. Each `n_runs` run uses seed, seed+1, seed+2, … `null` = random
`n_runs`	int	1	Number of independent simulations. Final result is the median-closest run

PMF Section¶

Steered MD¶

Parameter	Type	Recommended	Description
`v_pull_nm_ps`	float	0.01	Pulling velocity in nm/ps
`k_pull`	float	500.0	Stiff restraint spring constant (kJ/mol/nm²). Must be large enough to follow the target
`steps_steered_md`	int	70000	Steered MD steps. Must cover the full trajectory. At v=0.01 nm/ps and dt=0.01 ps: total pull = 0.01 × 0.01 × 70000 = 7 nm

Umbrella Sampling¶

Parameter	Type	Recommended	Description
`n_windows`	int	25	Number of umbrella windows. More windows → finer PMF
`k_window`	float	50.0	Window spring constant (kJ/mol/nm²). Controls sampling width: σ = √(kBT/k_window)
`steps_per_window`	int	200000	Sampling steps per window. More → better WHAM convergence
`steps_equil_window`	int	5000	Equilibration steps per window (not collected for histograms)
`window_min_nm`	float	auto	Manual PMF range start (nm). Default: actual adsorbed ξ
`window_max_nm`	float	auto	Manual PMF range end. Default: smart detection (Morse scan + Debye buffer)

Window Overlap Rule of Thumb¶

The standard deviation of ξ in each window is:

\[ \sigma = \sqrt{\frac{k_BT}{k_\text{window}}} \]

For WHAM to converge, the window spacing (= range / (n_windows − 1)) must be < 2σ. With the defaults:

k_window = 50 → σ ≈ 0.23 nm
25 windows over ~4 nm range → spacing ≈ 0.17 nm
overlap ratio = 0.23 / 0.17 ≈ 1.4× ✓

AdsPro prints the overlap ratio during the run. If it shows "WARNING: poor overlap", reduce k_window or add more windows.

Proteins Section¶

A list of one or more proteins to simulate sequentially.

Field	Type	Description
`pdb_file`	string	Filename of the PDB file in `input/<project>/`
`ph`	float	pH for charge assignment. Typical: 7.4 (physiological)

Multiple proteins are listed as a YAML sequence:

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

Common Configurations¶

Production (most accurate)¶

simulation:
  max_steps:  100000
  n_runs:     3

pmf:
  n_windows:          25
  k_window:           50.0
  steps_per_window:   200000
  steps_equil_window: 5000

Fast screening¶

simulation:
  max_steps:  10000
  n_runs:     1

pmf:
  n_windows:          15
  k_window:           50.0
  steps_per_window:   50000
  steps_equil_window: 2000

Multi-protein (one NP, many proteins)¶

simulation:
  max_steps: 50000
  n_runs:    1

proteins:
  - pdb_file: Lysozyme.pdb
    ph: 7.4
  - pdb_file: Albumin.pdb
    ph: 7.4
  - pdb_file: IgG.pdb
    ph: 7.4