Kholland: Created page with "last update: july7 2026 katie. ChemSTEP (Chemical Space Traversal and Exploration Procedure) is an open-source, transparent acceleration algorithm for molecular docking capable of dealing with virtual libraries of several trillion compounds. This wiki page is a guide for BKS lab members to run ChemSTEP on Wynton HPC, using a subset of ZINC (22B or 72B) or 13.3B library from Enamine REAL. At a high-level, ChemSTEP is an iterative process that identifies molecules from..."

2026-07-07T17:20:38Z

Created page with "last update: july7 2026 katie. ChemSTEP (Chemical Space Traversal and Exploration Procedure) is an open-source, transparent acceleration algorithm for molecular docking capable of dealing with virtual libraries of several trillion compounds. This wiki page is a guide for BKS lab members to run ChemSTEP on Wynton HPC, using a subset of ZINC (22B or 72B) or 13.3B library from Enamine REAL. At a high-level, ChemSTEP is an iterative process that identifies molecules from..."

New page

last update: july7 2026 katie.

ChemSTEP (Chemical Space Traversal and Exploration Procedure) is an open-source, transparent acceleration algorithm for molecular docking capable of dealing with virtual libraries of several trillion compounds. This wiki page is a guide for BKS lab members to run ChemSTEP on Wynton HPC, using a subset of ZINC (22B or 72B) or 13.3B library from Enamine REAL.

At a high-level, ChemSTEP is an iterative process that identifies molecules from the larger virtual library to prioritize for docking. First, we identify a random sample of the total library (termed "seed set", round zero) and dock those molecules to the target of interest. From this seed set, we can calculate total-library pProp values (-log rank percentages) and the number of "virtual hits" in the total library (high-scoring molecules). ChemSTEP will identify a set of maximally diverse molecules that score above the desired pProp threshold ("beacons") from the seed set. These beacons guide prioritization, where molecules chosen and output by ChemSTEP are close in chemical space to the beacons. Prioritized molecules are then built, docked, and returned to ChemSTEP for a second round of prioritization. This process is iterated until you reach desired virtual hit recovery, or you are no longer recovering virtual hits.

= Running ChemSTEP (Auto DOCK and Build with SymDOCK) =

ChemSTEP is configured to run on Wynton with libraries of '''13B''', '''22B''' (HAC 17-26, cLogP <= 3.5), and '''72B''' (HAC4-49, cLogP <=4.0). This page covers the full workflow for running ChemSTEP with automatic submission of docking and building jobs.

__TOC__

== 1. Source Environment ==

<pre>
source /wynton/group/bks/work/shared/kholland/chemstep_auto_symdock/symdock/bin/activate
</pre>

== 2. Dock the Seed Set ==

Copy the <code>.sdi</code> file for the library you want to use into a directory called '''sdi''' at the same level as your dockfiles:

{| class="wikitable"
! Library !! Path
|-
| 13B || <code>/wynton/group/bks/work/shared/kholland/chemstep_auto_v04/v04/scripts/libraries/13B/13M_seeds.wynton.sdi</code>
|-
| 22B || <code>/wynton/group/bks/work/shared/kholland/chemstep_auto_v04/v04/scripts/libraries/22B/22M_seeds.sdi</code>
|-
| 72B || <code>/wynton/group/bks/work/shared/kholland/chemstep_auto_v04/v04/scripts/libraries/72B/72M_seeds.sdi</code>
|}

DOCK the seed set:

<pre>
bash /wynton/group/bks/work/shared/kholland/chemstep_auto_symdock/subScripts/submit_symdock.sh
</pre>

== 3. Gather Scores for the Seed Set ==

Once docking is complete, run the following from the directory '''one level above''' your docking output (where dockfiles and sdi directories are).

'''22B/72B library:'''
<pre>
python /wynton/group/bks/work/shared/kholland/chemstep_auto_v04/v04/scripts/get_scores.py 0
</pre>

'''13B library:'''
<pre>
python /wynton/group/bks/work/shared/kholland/chemstep_auto_v04/v04/scripts/get_scores.py 0 MOL
</pre>

Note: You must specify the molecule ID prefix for the 13B library (<code>MOL</code>)

Verify that <code>scores_round_0.txt</code> was correctly written:
<pre>
wc -l scores_round_0.txt
</pre>

== 4. Convert Scores to .npy Files ==

Convert scores to ChemSTEP-readable <code>.npy</code> files:

<pre>
python /wynton/group/bks/work/shared/kholland/chemstep_auto_v04/v04/scripts/convert_scores_to_npy.py 0 <mol_id_prefix>
</pre>

The <code>mol_id_prefix</code> should match the library:

{| class="wikitable"
! Library !! Prefix
|-
| 22B / 72B || <code>CSLB</code>
|-
| 13B || <code>MOL</code>
|}

== 5. Set Up the ChemSTEP Run Directory ==

Create and enter a ChemSTEP run directory, then copy in the necessary files (with the ChemSTEP SymDOCK environment sourced):

<pre>
mkdir chemstep_run
cd chemstep_run
chemstep-run-new
</pre>

This will populate the directory with <code>params.txt</code>, <code>run_chemstep.py</code>, and <code>launch_chemstep_as_job.sh</code>.

=== Optional: Integrated IFP ===

If running with integrated IFP for beacon selection, also run:

<pre>
chemstep-run-ifp
</pre>

This copies in the additional files <code>ifp_acceptance_criteria.txt</code> and <code>interactions.txt</code>.

== 6. Edit params.txt ==

Add the absolute paths to the ChemSTEP-readable score and indices <code>.npy</code> arrays generated in Step 4.

<pre>
seed_indices_file: /path/to/your/indices_round_0.npy
seed_scores_file: /path/to/your/scores_round_0.npy
hit_pprop: 5.5
n_docked_per_round: 2000000
bundle_size: 1000
max_beacons: 100
max_n_rounds: 250
</pre>

=== Parameter Reference ===

{| class="wikitable"
! Parameter !! Description
|-
| <code>hit_pprop</code> || Defines a "virtual hit." pProp = −log(rank%) within the total library score distribution. E.g., pProp 4 in 13B space ≈ top 0.01% (~1.3M molecules); pProp 5 ≈ 0.001% (~132K). The seed set should contain at least 10<sup>(pProp+2)</sup> molecules.
|-
| <code>n_docked_per_round</code> || Number of molecules prioritized per round. All must be built and docked between rounds. Too many slows throughput and may reduce diversity; too few slows virtual hit recovery. Recommended: 1-2 million
|-
| <code>max_beacons</code> || Diverse, well-scoring molecules used to guide prioritization. All molecules above the pProp threshold are candidates. Too many reduce inter-beacon diversity; too few hinder space exploration. Fewer beacons than specified may be assigned if an insufficient number of molecules clear the threshold. Recommended: 100
|-
| <code>bundle_size</code> || In auto docking mode, number of molecules submitted as a single build job.
|-
| <code>max_n_rounds</code> || No adjustment needed when running ChemSTEP prospectively as described here.
|}

== 7. Edit run_chemstep.py ==

'''Note:''' All paths must be '''absolute paths'''.

=== Required Settings ===

Set <code>lib_path</code> to the library pickle for your library:

{| class="wikitable"
! Library !! Path
|-
| 13B || <code>/wynton/group/bks/work/shared/kholland/chemstep_auto_v04/v04/scripts/libraries/13B/boltz_fplib.pickle</code>
|-
| 22B || <code>/wynton/group/bks/work/shared/kholland/chemstep_auto_v04/v04/scripts/libraries/22B/22B_fplib.pickle</code>
|-
| 72B || <code>/wynton/group/bks/work/shared/kholland/chemstep_auto_v04/v04/scripts/libraries/72B/72B_fplib.pickle</code>
|}

<pre>
lib_path = '/full/path/to/library.pickle'
</pre>

Set <code>dockfiles_path</code>:

<pre>
dockfiles_path="/full/path/to/dockfiles"
</pre>

=== Optional: minTD Exclusion Zone ===

Molecules will not be prioritized from within a specified Tanimoto distance of beacons. Comment in the relevant lines and update the value. Consider also setting <code>enforce_n_docked_per_round = True</code> when using this option:

<pre>
min_td_search=0.5,
enforce_n_docked_per_round=True,
</pre>

=== Optional: Integrated IFP ===

Only selects beacons that satisfy user-defined interaction criteria. Comment in the following lines and update the paths to the necessary files (copied in Step 5 if you ran <code>chemstep-run-ifp</code>):

<pre>
use_IFP=True,
ifp_pdb_path='/full/path/to/rec.crg.pdb',
interactions_file='/full/path/to/interactions.txt',
ifp_acceptance_criteria_file='/full/path/to/ifp_acceptance_criteria.txt',
</pre>

'''<code>interactions.txt</code>''' — one interaction per line, comma-separated. Format: <code>interaction_type, residue_name_and_number</code>. Example:

<pre>
Hydrogen bond, GLY-19
Ionic, ASP-149
</pre>

Supported interaction types include: Proximal, Hydrogen bond, Ionic, Cation-pi, Hydrophobic, Halogen bond, and others. See LUNA and IFP documentation for the full list.

'''<code>ifp_acceptance_criteria.txt</code>''' — defines the number of unsatisfied donors/acceptors/specific interactions required for a molecule to pass IFP and be considered for beacon selection. Example:

<pre>
#_donors
#_acceptors
#_unstatisfied_donors == 0
#_unstatisfied_acceptors <= 4
Ionic/ASP-149 > 0
</pre>

=== Optional: SMARTS exclusion filter ===
Integrated SMARTS filer can exclude problematic chemotypes from being built, docked, or selected as beacons. Multiple SMARTS patterns are tolerated. Comment in the following line in run_chemstep.py:

<pre>
filter_smarts=['n1cncnc1', 'c1cccnc1[SH]']
</pre>

TRIAZINES: 'n1cncnc1'

=== Example: AmpC on 22B with minTD=0.50, No IFP ===

<pre>
lib_path = '/wynton/group/bks/work/shared/kholland/chemstep_auto_v04/scripts/libraries/22B/22B_fplib.pickle'
lib = load_library_from_pickle(lib_path)
algo = CSAlgo(lib, 'params.txt', 'output', 16, verbose=True,
scheduler='sge', smi_id_prefix='CSLB',
python_exec="/wynton/group/bks/work/shared/kholland/chemstep_auto_v04/bin/python",
dockfiles_path="/wynton/group/bks/work/kholland/chemstep_ampc_22B/seed_docking/dockfiles",
min_td_search=0.5,
enforce_n_docked_per_round=True,
#use_IFP=True,
#ifp_pdb_path='/path/to/your/reference/rec.crg.pdb',
#interactions_file='/path/to/your/interactions.txt',
#ifp_acceptance_criteria_file='/path/to/your/ifp_acceptance_criteria.txt',
docking_method="auto", track_beacon_orig=True)
</pre>

== 8. Launch the Job ==

Submit the main ChemSTEP job:

<pre>
qsub launch_chemstep_as_job.sh
</pre>

== 9. Monitor Job Status ==

Check job status with <code>qstat</code>. The main job will run for up to '''2 weeks''' given no errors. ChemSTEP will launch search, building, and docking jobs in successive rounds.

'''Note:''' If any building or docking subjobs hang, the main job will not proceed until those are canceled or finished. Monitor job statuses regularly and occasionally verify that docking output files (<code>scores_round_*.txt</code>) are being populated.

== 10. View Beacon SMILES and IDs ==

From the ChemSTEP running directory, run the following in a '''screen session on a dev node''':

<pre>
python /wynton/group/bks/work/shared/kholland/chemstep_auto_v04/v04/scripts/get_beacon_ids_smiles.py output/complete_info/beacons.df /path/to/fp/library output.txt
</pre>

{| class="wikitable"
! Library !! Path
|-
| 13B || <code>/wynton/group/bks/work/omailhot/chunked_ampc_chemstep_lib</code>
|-
| 22B || <code>/wynton/group/bks/work/kholland/22B_fp_library</code>
|-
| 72B || <code>/wynton/group/bks/work/kholland/72B_fp_library</code>
|}

Use the library pickle path from [[#7. Edit run_chemstep.py|Step 7]].

== 11. Plot Hit Recovery ==

In your ChemSTEP directory containing <code>chemstep_algo.log</code> and score files,
<pre>
bash /wynton/group/bks/work/shared/kholland/chemstep_auto_v04/v04/scripts/submit_hit_recovery.sh
</pre>

== 12. Get Poses After Docking ==

Make a list of <code>test.mol2.gz.0</code> files from docking:

<pre>
find round_*_docking/bundle_paths -maxdepth 2 -name "test.mol2.gz.0" > docked_poses.txt
</pre>

Then extract top poses:

<pre>
python /wynton/group/bks/work/bwhall61/for_beau/top_poses.py -t <pProp_energy_threshold> -s <num_poses_per_file> docked_poses.txt
</pre>

Get poses for Beacons:
<pre> python /wynton/group/bks/work/shared/kholland/chemstep_auto_v04/v04/scripts/get_beacon_poses.py output/complete_info/beacons.df /path/to/fp/library/ docked_poses.txt -o beacon_poses -j 8
</pre>

Running ChemSTEP with SymDOCK - Revision history