# System definition file¶

Although known previously as the receptor .prm file, the system definition file has evolved to contain much more than the receptor information. The system definition file is used to define:

## Receptor definition¶

The receptor can be loaded from a single MOL2 file, or from a combination of Charmm PSF and CRD files. In the former case the MOL2 file provides the topology and reference coordinates simultaneously, whereas in the latter case the topology is loaded from the PSF file and the reference coordinates from the CRD file. For historical compatibility reasons, receptor definition parameters are all defined in the top-level namespace and should not be placed between SECTION / END_SECTION pairs.

Caution

If MOL2 and PSF/CRD parameters are defined together, the MOL2 parameters take precedence and are used to load the receptor model.

Table 11 Receptor definition parameters

Parameter

Description

Type

Default

Range of values

RECEPTOR_FILE

Name of receptor MOL2 file

Filename string

No default value

Valid MOL2 filename

RECEPTOR_TOPOL_FILE

Name of receptor Charmm PSF file

Filename string

No default value

Valid Charmm PSF filename

RECEPTOR_COORD_FILE

Name of receptor Charmm CRD file

Filename string

No default value

Valid Charmm CRD filename

RECEPTOR_MASSES_FILE

Name of RxDock-annotated Charmm masses file

Filename string

No default value

masses.rtf, top_all2_prot_na.inp

General receptor parameters, applicable to either file format

RECEPTOR_SEGMENT_NAME

List of molecular segment names to read from either MOL2 or PSF/CRD file. If this parameter is defined, then any segment/chains not listed are not loaded. This provides a convenient way to remove cofactors, counterions and solvent without modifying the original file.

Comma separated list of segment name strings (without any spaces)

Empty (i.e. all segments read from file)

Comma separated list of segment name strings

RECEPTOR_FLEX

Defines terminal OH and NH3+ groups withing this distance of docking volume as flexible.

float (Angstroms)

Undefined (rigid receptor)

>0.0 (3.0 is a reasonable value)

Advanced parameters (should not need to be changed by the user)

RECEPTOR_ALL_H

Disable the removal of explicit non-polar hydrogens from the receptor model. Not recommended

boolean

FALSE

TRUE or FALSE

DIHEDRAL_STEP

Maximum mutation step size for receptor dihedral degrees of freedom.

float (degrees)

30.0

>0.0

## Ligand definition¶

Ligand definition parameters need only be defined if you wish to introduce tethering of some or all of the ligand degrees of freedom. If you are running conventional free docking then this section is not required. All ligand definition parameters should be defined in SECTION LIGAND. Note that the ligand input SD file continues to be specified directly on the rbdock command-line and not in the system definition file.

Table 12 Ligand definition parameters

Parameter

Description

Type

Default

Range of values

Main user parameters

TRANS_MODE

Sampling mode for ligand translational degrees of freedom

enumerated string literal

FREE

FIXED, TETHERED, FREE

ROT_MODE

Sampling mode for ligand whole-body rotational degrees of freedom

enumerated string literal

FREE

FIXED, TETHERED, FREE

DIHEDRAL_MODE

Sampling mode for ligand internal dihedral degrees of freedom

enumerated string literal

FREE

FIXED, TETHERED, FREE

MAX_TRANS

(for TRANS_MODE = TETHERED only) Maximum deviation allowed from reference centre of mass

float (Angstroms)

1.0

>0.0

MAX_ROT

(for ROT_MODE = TETHERED only) Maximum deviation allowed from orientation for reference principle axes

float (degrees)

30.0

>0.0–180.0

MAX_DIHEDRAL

(for DIHEDRAL_MODE = TETHERED only) Maximum deviation allowed from reference dihedral angles for any rotatable bond

float (degrees)

30.0

>0.0–180.0

Advanced parameters (should not need to be changed by the user)

TRANS_STEP

Maximum mutation step size for ligand translational degrees of freedom

float (Angstroms)

2.0

>0.0

ROT_STEP

Maximum mutation step size for ligand whole-body rotational degrees of freedom

float (degrees)

30.0

>0.0

DIHEDRAL_STEP

Maxium mutation step size for ligand internal dihedral degrees of freedom

float (degrees)

30.0

>0.0

## Solvent definition¶

Solvent definition parameters need only be defined if you wish to introduce explicit structural waters into the docking calculation, otherwise this section is not required. All solvent definition parameters should be defined in SECTION SOLVENT.

Table 13 Solvent definition parameters

Parameter

Description

Type

Default

Range of values

Main user parameters

FILE

Name of explicit solvent PDB file

File name string

No default value (mandatory parameter)

Valid PDB filename

TRANS_MODE

Sampling mode for solvent translational degrees of freedom. If defined here, the value overrides the per-solvent translational sampling modes defined in the solvent PDB file

enumerated string literal

FREE

FIXED, TETHERED, FREE

ROT_MODE

Sampling mode for solvent whole-body rotational degrees of freedom. If defined here, the value overrides the per-solvent rotational sampling modes defined in the solvent PDB file

enumerated string literal

FREE

FIXED, TETHERED, FREE

MAX_TRANS

(for TRANS_MODE = TETHERED waters only) Maximum deviation allowed from reference water oxygen positions. The same value is applied to all waters with TRANS_MODE = TETHERED; it is no possible currently to define per-solvent MAX_TRANS values

float (Angstroms)

1.0

>0.0

MAX_ROT

(for ROT_MODE = TETHERED waters only) Maximum deviation allowed from orientation of reference principal axes. The same value is applied to all waters with ROT_MODE = TETHERED; it is no possible currently to define per-solvent MAX_ROT values

float (degrees)

30.0

>0.0–180.0

OCCUPANCY

Controls occupancy state sampling for all explicit solvent. If defined here, the values overrides the per-solvent occupancy states defined in the solvent PDB file

float

1.0

0.0–1.0

Advanced parameters (should not need to be changed by the user)

TRANS_STEP

Maximum mutation step size for solvent translational degrees of freedom

float (Angstroms)

2.0

>0.0

ROT_STEP

Maximum mutation step size for solvent wholebody rotational degrees of freedom

float (degrees)

30.0

>0.0

OCCUPANCY_STEP

Maximum mutation step size for solvent occupancy state degrees of freedom

float (degrees)

1.0

0.0–1.0

Solvent occupancy state sampling OCCUPANCY = 0 permanently disables all solvent; OCCUPANCY = 1.0 permanently enables all solvent; OCCUPANCY between 0 and 1 activates variable occupancy state sampling, where the value represents the initial probability that the solvent molecule is enabled. For example, OCCUPANCY = 0.5 means that the solvent is enabled in 50 % of the initial GA population. However, the probability that the solvent is actually enabled in the final docking solution will depend on the particular ligand, the scoring function terms, and on the penalty for solvent binding. The occupancy state chromosome value is managed as a continuous variable between 0.0 and 1.0, with a nominal mutation step size of 1.0. Chromosome values lower than the occupancy threshold (defined as 1.0 - OCCUPANCY) result in the solvent being disabled; values higher than the threshold result in the solvent being enabled.

## Cavity mapping¶

The cavity mapping section is mandatory. You should choose one of the mapping algorithms shown below. All mapping parameters should be defined in SECTION MAPPER.

Table 14 Two sphere site mapping parameters

Parameter

Description

Type

Default

Range of values

Main user parameters

SITE_MAPPER

Mapping algorithm specifier

string literal

RbtSphereSiteMapper

fixed

CENTER

(x,y,z) center of cavity mapping region

Bracketed cartesian coordinate string (x,y,z)

None

None

RADIUS

float (Angstroms)

10.0

>0.0 (10.0–20.0 suggested range)

SMALL_SPHERE

float (Angstroms)

1.5

>0.0 (1.0–2.0 suggested range)

LARGE_SPHERE

float (Angstroms)

4.0

>SMALL_SPHERE (3.5–6.0 suggested range)

MAX_CAVITIES

Maximum number of cavities to accept (in descending order of size)

integer

99

>0

Advanced parameters (less frequently changed by the user)

VOL_INCR

Receptor atom radius increment for excluded volume

float (Angstroms)

0.0

>=0.0

GRID_STEP

Grid resolution for mapping

float (Angstroms)

0.5

>0.0 (0.3–0.8 suggested range)

MIN_VOLUME

Minimum cavity volume to accept (in Å3, not grid points)

float (Angstroms3)

100

>0 (100–300 suggested range)

Table 15 Reference ligand site mapping parameters

Parameter

Description

Type

Default

Range of values

Main user parameters

SITE_MAPPER

Mapping algorithm specifier

string literal

RbtLigandSiteMapper

fixed

REF_MOL

Reference ligand SD file name

string

ref.sd

None

RADIUS

float (Angstroms)

10.0

>0.0 (10.0–20.0 suggested range)

SMALL_SPHERE

float (Angstroms)

1.5

>0.0 (1.0–2.0 suggested range)

LARGE_SPHERE

float (Angstroms)

4.0

>SMALL_SPHERE (3.5–6.0 suggested range)

MAX_CAVITIES

Maximum number of cavities to accept (in descending order of size)

integer

99

>0

Advanced parameters (less frequently changed by the user)

VOL_INCR

Receptor atom radius increment for excluded volume

float (Angstroms)

0.0

>=0.0

GRID_STEP

Grid resolution for mapping

float (Angstroms)

0.5

>0.0 (0.3–0.8 suggested range)

MIN_VOLUME

Minimum cavity volume to accept (in Å3, not grid points)

float (Å3)

100

>0 (100–300 suggested range)

## Cavity restraint¶

The cavity restraint penalty function is mandatory and is designed to prevent the ligand from exiting the docking site. The function is calculated over all non-hydrogen atoms in the ligand (and over all explicit water oxygens that can translate). The distance from each atom to the nearest cavity grid point is calculated. If the distance exceeds the value of RMAX, a penalty is imposed based on the value of (distance - RMAX). The penalty can be either linear or quadratic depending on the value of the QUADRATIC parameter. It should not be necessary to change any the parameters in this section. Note that the docking protocol itself will manipulate the WEIGHT parameter, so any changes made to WEIGHT will have no effect.

SECTION CAVITY
SCORING_FUNCTION RbtCavityGridSF
WEIGHT 1.0
RMAX 0.1
END_SECTION


## Pharmacophore restraints¶

This section need only be defined if you wish to dock with pharmacophore restraints. If you are running conventional free docking then this section is not required. All pharmacophore definition parameters should be defined in SECTION PHARMA.

Table 16 Pharmacophore restraint parameters

Parameter

Description

Type

Default

Range of values

CONSTRAINTS_FILE

Mandatory pharmacophore restraints file

File name string

None (mandatory parameter)

Valid file name

OPTIONAL_FILE

Optional pharmacophore restraints file

File name string

None (optional parameter)

Valid file name, or empty

NOPT

Number of optional restraints that should be met

Integer

0

Between 0 and number of restraints in OPTIONAL_FILE

WRITE_ERRORS

Ligands with insufficient pharmacophore features to match the mandatory restraints are always removed prior to docking. If this parameter is true, the pre-filtered ligands are written to an error SD file with the same root name as the docked pose output SD file, but with an _errors.sd suffix. If false, the pre-filtered ligands are not written.

Boolean

FALSE

TRUE of FALSE

WEIGHT

Overall weight for the pharmacophore penalty function

Float

1.0

>=0.0

Calculation of mandatory restraint penalty The list of ligand atoms that matches each restraint type in the mandatory restraints file is precalculated for each ligand as it is loaded. If the ligand contains insufficient features to satisfy all of the mandatory restraints the ligand is rejected and is not docked. Note that the rejection is based purely on feature counts and does not take into account the possible geometric arrangements of the features. Rejected ligands are optionally written to an error SD file. The penalty for each restraint is based on the distance from the nearest matching ligand atom to the pharmacophore restraint centre. If the distance is less than the defined tolerance (restraint sphere radius), the penalty is zero. If the distance is greater than the defined tolerance a quadratic penalty is applied, equal to (nearest distance - tolerance)2.

Calculation of optional restraint penalty The individual restraint penalties for each restraint in the optional restraints file are calculated in the same way as for the mandatory penalties. However, only the NOPT lowest scoring (least penalised) restraints are summed for any given docking pose. Any remaining higher scoring optional restraints are ignored and do not contribute to the total pharmacophore restraint penalty.

Calculation of overall restraint penalty The overall pharmacophore restraint penalty is the sum of the mandatory restraint penalties and the NOPT lowest scoring optional restraint penalties, multiplied by the WEIGHT parameter value.

## NMR restraints¶

To be completed. However, this feature has rarely been used.

## Example system definition files¶

Full system definition file with all sections and common parameters enumerated explicitly:

RBT PARAMETER_FILE_V1.00
TITLE HSP90-PU3-lig-cavity, solvent flex=5
RECEPTOR_FILE PROT_W3_flex.mol2
RECEPTOR_SEGMENT_NAME PROT
RECEPTOR_FLEX 3.0
SECTION SOLVENT
FILE PROT_W3_flex_5.pdb
TRANS_MODE TETHERED
ROT_MODE TETHERED
MAX_TRANS 1.0
MAX_ROT 30.0
OCCUPANCY 0.5
END_SECTION
SECTION_LIGAND
TRANS_MODE FREE
ROT_MODE FREE
DIHEDRAL_MODE FREE
MAX_TRANS 1.0
MAX_ROT 30.0
MAX_DIHEDRAL 30.0
END_SECTION
SECTION MAPPER
SITE_MAPPER RbtLigandSiteMapper
REF_MOL ref.sd
SMALL_SPHERE 1.0
MIN_VOLUME 100
MAX_CAVITIES 1
VOL_INCR 0.0
GRIDSTEP 0.5
END_SECTION
SECTION CAVITY
SCORING_FUNCTION RbtCavityGridSF
WEIGHT 1.0
END_SECTION
SECTION PHARMA
SCORING_FUNCTION RbtPharmaSF
WEIGHT 1.0
CONSTRAINTS_FILE mandatory.const
OPTIONAL FILE optional.const
NOPT 3
WRITE_ERRORS TRUE
END_SECTION