SurfCo Integration¶

AdsPro is designed as the single-protein adsorption engine that powers SurfCo — the protein corona composition simulator. The two tools form a complete computational pipeline from protein structure to corona composition.

Overview¶

SurfCo (corona composition simulator)
  │
  ├── For each protein in plasma:
  │     └── AdsPro (single-protein adsorption engine)
  │           └── Returns: ΔG_ads, adsorbed conformation, contact map
  │
  └── DEDIK kinetic Monte Carlo engine
        └── Uses ΔG_ads to compute adsorption/desorption probabilities
              └── Returns: corona composition vs. time

AdsPro and SurfCo are separate tools. SurfCo calls AdsPro via the command line and reads its JSON output.

CLI Mode for SurfCo¶

When called by SurfCo, AdsPro runs in single-protein CLI mode — no config.yaml is needed. All parameters are passed as command-line arguments, and output is formatted as JSON for machine consumption:

python -m adspro \
  --pdb Lysozyme.pdb \
  --radius 71.3 \
  --zeta -0.050 \
  --material silica \
  --ionic-strength 20.0 \
  --ph 7.4 \
  --temperature 310.0 \
  --output-format json

The JSON output (to stdout) contains:

{
  "protein": "Lysozyme",
  "delta_G_ads_kJ_mol": -28.76,
  "pmf_converged": true,
  "xi_min_nm": 1.649,
  "e_morse_kJ_mol": -91.84,
  "contact_residues": [21, 128, 116, 13, 14, 112, 125, 114],
  "tilt_angle_deg": 51.07,
  "native_contact_retention": 0.735
}

SurfCo reads this JSON, extracts delta_G_ads_kJ_mol, and converts it to adsorption/desorption probabilities for the DEDIK engine.

How SurfCo Uses ΔG_ads¶

SurfCo models the protein corona as a kinetic Monte Carlo (kMC) process on the NP surface. At each kMC iteration:

Select an event (adsorption or desorption) with probability proportional to the event rates
The adsorption rate is proportional to \(P_\text{ads}\), derived from ΔG_ads via a Boltzmann factor
The desorption rate is the complement: \(P_\text{des} = 1 - P_\text{ads}\)

The probability functions (from Baas et al., adapted for AdsPro):

\[ P_\text{ads} = (1 - \theta) \cdot \frac{1}{1 + e^{E_\text{norm}/RT}} \]

\[ P_\text{des} = \frac{1}{1 + e^{-E_\text{norm}/RT}} \]

where \(\theta\) is the local surface coverage and \(E_\text{norm}\) is the normalized energy (scaled between user-specified min/max adsorption probabilities).

Project Structure in a Combined AdsPro + SurfCo Study¶

StudyDirectory/
├── adspro/          # AdsPro installation
│   └── input/
│       └── my_np/
│           ├── config.yaml
│           ├── Lysozyme.pdb
│           ├── BSA.pdb
│           └── ...
├── SurfCo/          # SurfCo installation
│   └── input/
│       └── my_corona/
│           └── config.yaml   # NP params + protein list + concentrations
└── results/
    ├── adspro/      # Per-protein ΔG_ads and conformations
    └── surfco/      # Corona composition vs. time

Typical workflow: 1. Run AdsPro for each protein in your library → get ΔG_ads database 2. Configure SurfCo with your NP parameters and protein concentrations 3. SurfCo calls AdsPro for any protein not already in the database 4. DEDIK simulation produces corona composition at each time point

Performance Considerations¶

For a corona study with 20 proteins:

AdsPro phase: 20 proteins × ~3 hours each = ~60 hours total (can be parallelized across machines)
SurfCo phase: DEDIK is fast (minutes to hours depending on simulation time and NP size)

The AdsPro results are cached — if you run SurfCo again with different protein concentrations or temperatures, the ΔG_ads values do not need to be recomputed.