Free Energy

class FreeEnergyProject(client, calculate_program=Program.AMBER, calculate_application=Application.RELATIVE_BINDING)

Bases: BaseProject

A class for creating and manipulating AFES projects.

Parameters:
add_boresh_restraint(lig_ff, ligand_name, receptor_info, ligand_atom_name)

Add one Boresch restraint atom pair for ABFE setup.

Parameters:

  • lig_ff (LigandForceField) – Ligand force field key.

  • ligand_name (str) – Ligand name.

  • receptor_info (dict) – Receptor atom info.

  • ligand_atom_name (str) – Ligand atom name.

Returns:

None

add_core_indices(lig_ff, ligand_name, indices, set_num=1, group_index=0)

Add core atom indices for a ligand in selected set/group.

Parameters:

  • lig_ff (LigandForceField) – Ligand force field key.

  • ligand_name (str) – Ligand name.

  • indices – Index or list of indices to add.

  • set_num (int) – Morph set number (1-based).

  • group_index (int) – Ligand group index for BLaDE.

Returns:

None

add_ligand_group(lig_ff, ligand_names)

Create a new hybrid ligand group from ligand names.

Parameters:

  • lig_ff (LigandForceField) – Ligand force field key.

  • ligand_names (list[str]) – Ligand names for new group.

Returns:

None

add_ligand_to_group(lig_ff, group_index, ligand_name)

Add one ligand to an existing hybrid ligand group.

Parameters:

  • lig_ff (LigandForceField) – Ligand force field key.

  • group_index (int) – Group index (0-based).

  • ligand_name (str) – Ligand name to add.

Returns:

None

add_morph_set(lig_ff, morph_set)

Add a morph connection to generated morph sets.

Parameters:

  • lig_ff (LigandForceField) – Ligand force field key.

  • morph_set (dict[str, Any]) – Morph edge info with start and end.

Returns:

None

apply_force_constant(distance, angle, dihedral)

Set force constants used in ABFE restraints.

Parameters:

  • distance (float) – Distance restraint constant.

  • angle (float) – Angle restraint constant.

  • dihedral (float) – Dihedral restraint constant.

Returns:

None

check_ligand_2d_structure(file_name_1, file_name_2)

Display two ligand 2D structures side by side for comparison.

Parameters:

  • file_name_1 (str) – First ligand file name.

  • file_name_2 (str) – Second ligand file name.

Returns:

None

check_reference_ligands()

Check available reference ligands in the linked reference project.

Parameters:

None

Returns:

List of ligand dictionaries with chain/residue info.

Return type:

list[dict]

create_project(title, reference_project_id, ff=ForceField.AMBER, calculate_program=Program.AMBER, calculate_application=Application.RELATIVE_BINDING, amber_options={'protein': Protein.FF19SB, 'water': Water.OPC})

Create a new alchemical free-energy project.

Parameters:

  • title (str) – Project title.

  • reference_project_id (str) – Solution/Membrane Builder project ID.

  • ff (ForceField) – Protein force field type.

  • calculate_program (Program) – FE backend program.

  • calculate_application (Application) – FE application type.

  • calculate_method (Method) – FE method.

  • amber_options (dict[str, StrEnum]) – AMBER options.

Returns:

True if project creation was successful, False otherwise.

Return type:

bool

Example

afes.create_project(title=’my_afes_project’, reference_project_id=sbuilder.projectId)

delete_boresh_restraint(lig_ff, ligand_name, delete_indices)

Delete one or more Boresch restraints by index.

Parameters:

  • lig_ff (LigandForceField) – Ligand force field key.

  • ligand_name (str) – Ligand name.

  • delete_indices – Indices to remove.

Returns:

None

delete_core_indices(lig_ff, ligand_name, indices, set_num=1, group_index=0)

Delete core atom indices for a ligand in selected set/group.

Parameters:

  • lig_ff (LigandForceField) – Ligand force field key.

  • ligand_name (str) – Ligand name.

  • indices – Index or list of indices to delete.

  • set_num (int) – Morph set number (1-based).

  • group_index (int) – Ligand group index for BLaDE.

Returns:

None

delete_ligand_from_group(lig_ff, group_index, ligand_name)

Remove one ligand from an existing hybrid ligand group.

Parameters:

  • lig_ff (LigandForceField) – Ligand force field key.

  • group_index (int) – Group index (0-based).

  • ligand_name (str) – Ligand name to remove.

Returns:

None

delete_ligand_group(lig_ff, group_index)

Delete a hybrid ligand group by index.

Parameters:

  • lig_ff (LigandForceField) – Ligand force field key.

  • group_index (int) – Group index (0-based).

Returns:

None

delete_morph_set(lig_ff, morph_set)

Delete a morph connection from generated morph sets.

Parameters:

  • lig_ff (LigandForceField) – Ligand force field key.

  • morph_set (dict[str, Any]) – Morph edge info with start and end.

Returns:

None

delete_mutation(delete_index)

Delete a configured mutation by list index.

Parameters:

delete_index (int) – Zero-based mutation index.

Returns:

None

download_project(filename='afes.tar.gz')

Download AFES project archive.

Parameters:

filename (str) – Output archive file path.

Returns:

None

generate_ligand_group(ligand_ff, ligand_modeler_project_id='', selected_ligands={})

Generate pre-ligand group suggestions for BLaDE relative binding.

Parameters:

  • reference_ligand (dict) – Target ligand mapping in receptor.

  • ligand_ff (list[LigandForceField]) – Ligand force fields to use.

  • ligand_modeler_project_id (str) – LRM project ID.

  • selected_ligands (dict[LigandForceField, list[str]]) – Ligand subset by FF.

Returns:

None

generate_morph_set(ligand_ff, ligand_modeler_project_id='', selected_ligands={}, generate_morphset_type=GenerateMorphsetType.CLOSED, threshold=1)

Generate perturbation-path morph sets from selected ligands.

Parameters:

  • reference_ligand (dict) – Target ligand mapping in receptor.

  • ligand_ff (list[LigandForceField]) – Ligand force fields to use.

  • ligand_modeler_project_id (str) – LRM project ID.

  • selected_ligands (dict[LigandForceField, list[str]]) – Ligand subset by FF.

  • generate_morphset_type (GenerateMorphsetType) – Morph generation type.

  • threshold (int) – Clustering threshold.

Returns:

None

Example

afes.generate_morph_set(reference_ligand=reference_ligand, ligand_ff=[LigandForceField.GAFF_FAST])

generate_system(ion_type='kcl', ion_conc=0.15, use_hmr=False, temperature=310.15, margin=10)

Generate final FE simulation system from prepared workflow state.

Parameters:

  • ion_type (str) – Ion type.

  • ion_conc (float) – Ion concentration.

  • use_hmr (bool) – Whether to use hydrogen mass repartitioning.

  • temperature (float) – System temperature in Kelvin.

  • margin (float) – Water box margin.

Returns:

True if generation task succeeded, False otherwise.

Return type:

bool

Example

afes.generate_system(ion_type=’kcl’, ion_conc=0.15)

get_closest_atoms(lig_ff, ligand_name='')

Compute and visualize closest receptor-ligand atom candidates for ABFE.

Parameters:

  • lig_ff (LigandForceField) – Ligand force field key.

  • ligand_name (str) – Optional target ligand name.

Returns:

None

get_core_indices(lig_ff, ligand_name='', set_num=1, group_index=0)

Show current core indices and visualize highlighted atoms.

Parameters:

  • lig_ff (LigandForceField) – Ligand force field key.

  • ligand_name (str) – Ligand name for non-morph workflows.

  • set_num (int) – Morph set number (1-based).

  • group_index (int) – Ligand group index for BLaDE.

Returns:

None

get_distance(lig_ff=None, ligand_name='')

Open interactive 3D distance measurement view for receptor-ligand atoms.

Parameters:

  • lig_ff (LigandForceField) – Optional ligand FF to select ligand.

  • ligand_name (str) – Optional ligand name.

Returns:

None

get_ligand_groups(lig_ff)

Print current hybrid ligand groups for BLaDE workflow.

Parameters:

lig_ff (LigandForceField) – Ligand force field key.

Returns:

None

get_similarity_score(lig_ff)

Visualize ligand similarity matrix and dendrogram for one FF.

Parameters:

lig_ff (LigandForceField) – Ligand force field key.

Returns:

None

parse_avail_mutation()

Load mutation-FE required data from current project.

Parameters:

None

Returns:

None

processing_ligand(ligand_modeler_project_id='', ligand_ff=[], selected_ligands={})

Process ligand data and prepare step-2 FE configuration payload.

Parameters:

  • reference_ligand (dict) – Target ligand mapping in receptor.

  • ligand_modeler_project_id (str) – LRM project ID.

  • ligand_ff (list[LigandForceField]) – Ligand FF list.

  • selected_ligands (dict[LigandForceField, list[str]]) – Ligand subset by FF.

Returns:

Next-step preview result (depends on workflow) or False.

Return type:

Any

Example

afes.processing_ligand()

read_ligand_modeler_project(project_id)

Read generated ligands from an existing LRM project.

Parameters:

project_id (str) – Ligand Reader & Modeler project ID.

Returns:

None

set_ligand_group(lig_ff, n_groups, max_rsub_count)

Set K and max R-substituent count for one ligand FF group config.

Parameters:

  • lig_ff (LigandForceField) – Ligand force field key.

  • n_groups (int) – Number of ligand groups.

  • max_rsub_count (int) – Max R-substituent per site.

Returns:

None

set_mutation(mutation_info)

Add one mutation entry to mutation configuration list.

Parameters:

mutation_info (dict) – Mutation info (chainIndex, resid, mutation).

Returns:

None

set_target_chain(chain_index)

Set mutation target chain for Mutation FE workflow.

Parameters:

chain_index (str) – Target chain index.

Returns:

None

update_boresh_restraint(lig_ff, ligand_name, target, receptor_info={}, ligand_atom_name='')

Update a selected receptor/ligand anchor in existing Boresch restraints.

Parameters:

  • lig_ff (LigandForceField) – Ligand force field key.

  • ligand_name (str) – Ligand name.

  • target (str) – One of p1, p2, p3, l1, l2, l3.

  • receptor_info (dict) – Receptor atom info for p* updates.

  • ligand_atom_name (str) – Ligand atom name for l* updates.

Returns:

None

update_ring_match(ring_match, lig_ff, set_num=1)

Update complete-ring-match flag for a selected morph set.

Parameters:

  • ring_match (bool) – Whether to enforce complete ring matching.

  • lig_ff (LigandForceField) – Ligand force field key.

  • set_num (int) – 1-based morph set index.

Returns:

None

Schemata

molcube.free_energy.conf

AMBER_AMINO_ACIDS = ['ALA', 'ARG', 'ASN', 'ASP', 'CYS', 'GLN', 'GLU', 'GLY', 'HID', 'HIE', 'HIP', 'ILE', 'LEU', 'LYS', 'MET', 'PHE', 'PRO', 'SER', 'THR', 'TRP', 'TYR', 'VAL']

AMBER Force Field

CHARMM_AMINO_ACIDS = ['ALA', 'ARG', 'ASN', 'ASP', 'CYS', 'GLN', 'GLU', 'GLY', 'HSD', 'HSE', 'HSP', 'ILE', 'LEU', 'LYS', 'MET', 'PHE', 'PRO', 'SER', 'THR', 'TRP', 'TYR', 'VAL']

CHARMM & Drude Force Fields

MARTINI_AMINO_ACIDS = ['ALA', 'ARG', 'ASN', 'ASP', 'CYS', 'GLN', 'GLU', 'GLY', 'HIS', 'ILE', 'LEU', 'LYS', 'MET', 'PHE', 'PRO', 'SER', 'THR', 'TRP', 'TYR', 'VAL']

Martini Force Field

molcube.free_energy.enum

class Application(*values)

Bases: StrEnum

ABSOLUTE_BINDING = 'absolute binding'
MUTATION_FE = 'mutation free energy'
RELATIVE_BINDING = 'relative binding'
class ForceField(*values)

Bases: StrEnum

AMBER = 'amberff'
CHARMM = 'charmmff'
class GenerateMorphsetType(*values)

Bases: StrEnum

CLOSED = 'closed'
CUSTOM = 'custom'
LOMAP = 'lomap'
MST = 'minimum_spanning_tree'
RADIAL = 'radial'
class LigandForceField(*values)

Bases: StrEnum

GAFF = 'gaff'
GAFF_FAST = 'gaff-fast'
OPENFF = 'openff'
OPENFF_FAST = 'openff-fast'
XFF = 'xff'
XFF_FAST = 'xff-fast'
class Method(*values)

Bases: StrEnum

FEP = 'fep'
MSLD = 'msld'
NON_EQ_TI = 'non-eq ti'
TI = 'ti'
class MutationResidueName(*values)

Bases: StrEnum

ALA = 'ALA'
ARG = 'ARG'
ASN = 'ASN'
ASP = 'ASP'
CYS = 'CYS'
GLN = 'GLN'
GLU = 'GLU'
GLY = 'GLY'
HID = 'HID'
HIE = 'HIE'
HIP = 'HIP'
HIS = 'HIS'
HSD = 'HSD'
HSE = 'HSE'
HSP = 'HSP'
ILE = 'ILE'
LEU = 'LEU'
LYS = 'LYS'
MET = 'MET'
PHE = 'PHE'
PRO = 'PRO'
SER = 'SER'
THR = 'THR'
TRP = 'TRP'
TYR = 'TYR'
VAL = 'VAL'
class Program(*values)

Bases: StrEnum

AMBER = 'amber'
BLADE = 'blade'
GROMACS = 'gromacs'
OPENMM = 'openmm'
class Protein(*values)

Bases: StrEnum

FF14SB = 'FF14SB'
FF14SBonlysc = 'FF14SBonlysc'
FF19SB = 'FF19SB'
class Water(*values)

Bases: StrEnum

OPC = 'OPC'
TIP3P = 'TIP3P'
TIP4PD = 'TIP4PD'
TIP4PEW = 'TIP4PEW'