schrodinger.application.desmond.cmj module

This module provides fundamental facilities for writing a multisim driver script, for writing multisim concrete stage classes, and for dealing with protocol files.

Copyright Schrodinger, LLC. All rights reserved.

schrodinger.application.desmond.cmj.print_tonull(msg)

schrodinger.application.desmond.cmj.print_silent(msg)

schrodinger.application.desmond.cmj.print_quiet(msg)

schrodinger.application.desmond.cmj.print_verbose(msg)

schrodinger.application.desmond.cmj.print_debug(msg)

class schrodinger.application.desmond.cmj.JobStatus(code=101)

Bases: object

WAITING = 101

RUNNING = 102

SUCCESS = 103

BACKEND_ERROR = 201

PERMANENT_LICENSE_FAILURE = 202

NON_RETRIABLE_FAILURE = 299

TEMPORARY_LICENSE_FAILURE = 301

KILLED = 302

FIZZLED = 303

LAUNCH_FAILURE = 304

FILE_NOT_FOUND = 305

FILE_CORRUPT = 306

STRANDED = 307

CHECKPOINT_REQUESTED = 308

CHECKPOINT_WITH_RESTART_REQUESTED = 309

RETRIABLE_FAILURE = 399

STRING = {101: 'is waiting for launching', 102: 'is running', 103: 'was successfully finished', 201: 'died due to backend error', 202: 'could not run due to permanent license failure', 299: 'died on unknown non-retriable failure', 301: 'died due to temporary license failure', 302: 'was killed', 303: 'fizzled', 304: 'failed to launch', 305: 'was finished, but registered output files were not found', 306: 'was finished, but an essential output file was found corrupt', 307: 'was stranded', 308: 'user requested job be checkpointed', 309: 'user requested job be checkpointed and restarted', 399: 'died on unknown retriable failure'}

__init__(code=101)

set(code, error=None)

is_good()

is_retriable()

should_restart_from_checkpoint()

class schrodinger.application.desmond.cmj.JobOutput

Bases: object

__init__()

__len__()

Returns the number of registered output files.

update_basedir(old_basedir, new_basedir)

add(filename, checker=None, tag=None, type='file')

Parameters

type – either “file” and “dir”.

remove(filename)

get(tag)

check(status)

set_struct_file(fname)

struct_file()

log_file()

class schrodinger.application.desmond.cmj.JobInput

Bases: schrodinger.application.desmond.cmj.JobOutput

cfg_file()

incfg_file()

outcfg_file()

class schrodinger.application.desmond.cmj.JobErrorHandler

Bases: object

static default(job)

If the job status is bad, attempt to print the log file and nvidia-smi output.

static restart_for_backend_error(job)

Run the default handler and if the status is killed or backend error, mark the failure as retriable.

schrodinger.application.desmond.cmj.exit_code_is_defined(job)

Return True if job has an exit code. Failed jobs may not have exit codes if they are killed by the queueing system or otherwise untrackable.

class schrodinger.application.desmond.cmj.Job(jobname, parent, stage, jlaunch_cmd, dir, host_list=None, prefix=None, what=None, err_handler=<function JobErrorHandler.default>, is_output=True)

Bases: object

USE_GPU = False

class Time(launch, start, end, num_cpu, cpu_time, duration)

Bases: object

__init__(launch, start, end, num_cpu, cpu_time, duration)

static get_time(jctrl, num_cpu)

get_proc_time()

__init__(jobname, parent, stage, jlaunch_cmd, dir, host_list=None, prefix=None, what=None, err_handler=<function JobErrorHandler.default>, is_output=True)

property is_for_jc: bool

Whether or not this job should be submitted to job control

property is_launchable: bool

property failed: bool

property is_retriable: bool

property is_incomplete: bool

property is_restartable

describe()

process_completed_job(jctrl: schrodinger.job.jobcontrol.Job, checkpoint_requested=False, restart_requested=False)

Check for valid output and set status of job, assuming job is already complete.

Parameters

• checkpoint_requested – Set to True if the job should checkpoint. Default if False.

• restart_requested – Set to True if the job should checkpoint and restart. Default if False.

requeue(jctrl: schrodinger.job.jobcontrol.Job)

finish()

class schrodinger.application.desmond.cmj.StageBase(should_pack=True)

Bases: schrodinger.application.desmond.picklejar.Picklable

count = 0

stage_cls = {'generic': <class 'schrodinger.application.desmond.stage.simulate.VrunBase'>, 'system_builder': <class 'schrodinger.application.desmond.stage.utils.SystemBuilder'>, 'simulate': <class 'schrodinger.application.desmond.stage.simulate.Simulate'>, 'replica_exchange': <class 'schrodinger.application.desmond.stage.simulate.ReplicaExchange'>, 'lambda_hopping': <class 'schrodinger.application.desmond.stage.simulate.LambdaHopping'>, 'desmond_extend': <class 'schrodinger.application.desmond.stage.simulate.DesmondExtend'>, 'vrun': <class 'schrodinger.application.desmond.stage.simulate.Vrun'>, 'fep_vrun': <class 'schrodinger.application.desmond.stage.simulate.FepVrun'>, 'concatenate': <class 'schrodinger.application.desmond.stage.simulate.Concatenate'>, 'reinit': <class 'schrodinger.application.desmond.stage.simulate.ReInit'>, 'primer': <class 'schrodinger.application.desmond.stage.workflow.Primer'>, 'concluder': <class 'schrodinger.application.desmond.stage.workflow.Concluder'>, 'task': <class 'schrodinger.application.desmond.stage.workflow.Task'>, 'extern': <class 'schrodinger.application.desmond.stage.workflow.Extern'>, 'trim': <class 'schrodinger.application.desmond.stage.workflow.Trim'>, 'stop': <class 'schrodinger.application.desmond.stage.workflow.Stop'>, 'assign_custom_charge': <class 'schrodinger.application.desmond.stage.prepare.forcefield.AssignCustomCharge'>, 'assign_forcefield': <class 'schrodinger.application.desmond.stage.prepare.forcefield.AssignForcefield'>, 'lambda_dynamics_assign_forcefield': <class 'schrodinger.application.desmond.stage.prepare.forcefield.LambdaDynamicsAssignForcefield'>, 'assign_lambda_schedule': <class 'schrodinger.application.desmond.stage.prepare.forcefield.AssignLambdaSchedule'>, 'load_restraints_from_structure': <class 'schrodinger.application.desmond.stage.prepare.forcefield.LoadRestraintsFromStructure'>, 'forcefield_builder_launcher': <class 'schrodinger.application.desmond.stage.prepare.forcefield.ForcefieldBuilderLauncher'>, 'build_geometry': <class 'schrodinger.application.desmond.stage.prepare.structure.BuildGeometry'>, 'lambda_dynamics_build_geometry': <class 'schrodinger.application.desmond.stage.prepare.structure.LambdaDynamicsBuildGeometry'>, 'extract_structures': <class 'schrodinger.application.desmond.stage.prepare.structure.ExtractStructures'>, 'extract_solute_structure': <class 'schrodinger.application.desmond.stage.prepare.structure.ExtractSoluteStructure'>, 'hash_structure_title': <class 'schrodinger.application.desmond.stage.prepare.structure.HashStructureTitle'>, 'disordered_system_builder': <class 'schrodinger.application.desmond.stage.prepare.structure.DisorderedSystemBuilder'>, 'protein_mutation_generator': <class 'schrodinger.application.desmond.stage.prepare.structure.ProteinMutationGenerator'>, 'replicate_structure': <class 'schrodinger.application.desmond.stage.prepare.structure.ReplicateStructure'>, 'group_waters': <class 'schrodinger.application.desmond.stage.prepare.structure.GroupWaters'>, 'pl_analysis': <class 'schrodinger.application.desmond.stage.analysis.PLAnalysis'>, 'analysis': <class 'schrodinger.application.desmond.stage.analysis.Analysis'>, 'fep_analysis': <class 'schrodinger.application.desmond.stage.analysis.FepAnalysis'>, 'multisim': <class 'schrodinger.application.desmond.stage.launcher.Multisim'>, 'fep_launcher': <class 'schrodinger.application.desmond.stage.launcher.FepLauncher'>, 'fep_membrane_launcher': <class 'schrodinger.application.desmond.stage.launcher.FepMembraneLauncher'>, 'covalent_fep_mapper': <class 'schrodinger.application.desmond.stage.fep_mapper.CovalentFepMapper'>, 'protein_fep_mapper': <class 'schrodinger.application.desmond.stage.fep_mapper.ProteinFepMapper'>, 'combined_protein_fep_mapper': <class 'schrodinger.application.desmond.stage.fep_mapper.CombinedProteinFepMapper'>, 'fep_mapper': <class 'schrodinger.application.desmond.stage.fep_mapper.FepMapper'>, 'fep_mapper_cleanup': <class 'schrodinger.application.desmond.stage.fep_mapper.FepMapperCleanup'>, 'calc_ddg': <class 'schrodinger.application.desmond.stage.fep_mapper.CalcDdg'>, 'fep_absolute_binding_structure_primer': <class 'schrodinger.application.desmond.stage.app.absolute_binding.stage.FepAbsoluteBindingStructurePrimer'>, 'fep_absolute_binding_fep_primer': <class 'schrodinger.application.desmond.stage.app.absolute_binding.stage.FepAbsoluteBindingFepPrimer'>, 'fep_absolute_binding_launcher_base': <class 'schrodinger.application.desmond.stage.app.absolute_binding.stage.FepAbsoluteBindingLauncherBase'>, 'fep_absolute_binding_md_launcher': <class 'schrodinger.application.desmond.stage.app.absolute_binding.stage.FepAbsoluteBindingMdLauncher'>, 'fep_absolute_binding_fep_launcher': <class 'schrodinger.application.desmond.stage.app.absolute_binding.stage.FepAbsoluteBindingFepLauncher'>, 'fep_absolute_binding_analysis': <class 'schrodinger.application.desmond.stage.app.absolute_binding.stage.FepAbsoluteBindingAnalysis'>, 'fragment_linking_primer': <class 'schrodinger.application.desmond.stage.app.fragment_linking.stage.FragmentLinkingPrimer'>, 'ramd': <class 'schrodinger.application.desmond.stage.app.kinetics.RandomAcceleratedMD'>, 'ramd_reactive_path': <class 'schrodinger.application.desmond.stage.app.kinetics.RamdGenerateUnbindingPath'>, 'validate_stability': <class 'schrodinger.application.desmond.stage.app.kinetics.ValidateStability'>, 'ramd_setup': <class 'schrodinger.application.desmond.stage.app.kinetics.RamdSetup'>, 'ramd_cleanup': <class 'schrodinger.application.desmond.stage.app.kinetics.RamdCleanup'>, 'path_unbinding': <class 'schrodinger.application.desmond.stage.app.kinetics.PathUnbinding'>, 'path_unbinding_analysis': <class 'schrodinger.application.desmond.stage.app.kinetics.PathUnbindingAnalysis'>, 'path_unbind_cleanup': <class 'schrodinger.application.desmond.stage.app.kinetics.PathUnbindingCleanup'>, 'lambda_dynamics_split_receptor': <class 'schrodinger.application.desmond.stage.app.lambda_dynamics.LambdaDynamicsSplitReceptor'>, 'lambda_dynamics_mapper': <class 'schrodinger.application.desmond.stage.app.lambda_dynamics.LambdaDynamicsMapper'>, 'lambda_dynamics_md_launcher': <class 'schrodinger.application.desmond.stage.app.lambda_dynamics.LambdaDynamicsMdLauncher'>, 'aacg_sitemap': <class 'schrodinger.application.desmond.stage.app.matsci.Aacg_SiteMap_Multijob'>, 'average_cell': <class 'schrodinger.application.desmond.stage.app.matsci.AverageCell'>, 'deform_cell': <class 'schrodinger.application.desmond.stage.app.matsci.DeformCell'>, 'solvate_slab_builder': <class 'schrodinger.application.desmond.stage.app.matsci.SolvateSlabBuilder'>, 'matsci_analysis': <class 'schrodinger.application.desmond.stage.app.matsci.MatSciAnalysis'>, 'ses_stage': <class 'schrodinger.application.desmond.stage.app.matsci.ScaleEffectiveSolvent'>, 'extract_subsystem': <class 'schrodinger.application.desmond.stage.app.matsci.ExtractSubSystem'>, 'frozen_phonon_correction': <class 'schrodinger.application.desmond.stage.app.matsci.FrozenPhononCorrection'>, 'mixed_solvent_setup': <class 'schrodinger.application.desmond.stage.app.mxmd.MixedSolventSetup'>, 'mixed_solvent_analysis': <class 'schrodinger.application.desmond.stage.app.mxmd.MixedSolventAnalysis'>, 'mixed_solvent_cleanup': <class 'schrodinger.application.desmond.stage.app.mxmd.MixedSolventCleanup'>, 'generate_mxmd_box': <class 'schrodinger.application.desmond.stage.app.mxmd.GenerateMxmdBox'>, 'analyze_mxmd_probe_mixture': <class 'schrodinger.application.desmond.stage.app.mxmd.AnalyzeMxmdProbeMixture'>, 'generate_solubility_fep_structures': <class 'schrodinger.application.desmond.stage.app.solubility.GenerateSolubilityFepStructures'>, 'solubility_md_launcher': <class 'schrodinger.application.desmond.stage.app.solubility.SolubilityMdLauncher'>, 'solubility_fep_launcher': <class 'schrodinger.application.desmond.stage.app.solubility.SolubilityFepLauncher'>, 'solubility_fep_analysis': <class 'schrodinger.application.desmond.stage.app.solubility.SolubilityFepAnalysis'>, 'watermap_cluster': <class 'schrodinger.application.desmond.stage.app.watermap.WaterMapCluster'>, 'watermap_post_analysis': <class 'schrodinger.application.desmond.stage.app.watermap.WaterMapPostAnalysis'>, 'constant_ph_analysis': <class 'schrodinger.application.desmond.stage.app.constant_ph.ConstantpHAnalysis'>, 'lambda_dynamics_analysis': <class 'schrodinger.application.desmond.stage.app.lambda_dynamics_analysis.LambdaDynamicsAnalysis'>, None: <class 'schrodinger.application.desmond.stage.deprecate.MustSkip'>, 'ffbuilder': <class 'schrodinger.application.desmond.stage.deprecate.ForcefieldBuilder'>, 'align_core': <class 'schrodinger.application.desmond.stage.deprecate.AlignCore'>, 'solvate_pocket': <class 'schrodinger.application.desmond.stage.deprecate.SolvatePocket'>, 'vacuum_report': <class 'schrodinger.application.desmond.stage.deprecate.VacuumReport'>, 'fep_mapper_report': <class 'schrodinger.application.desmond.stage.deprecate.FepMapperReport'>}

stage_obj = {}

NAME = 'generic'

RESTARTABLE = False

PARAM = <schrodinger.utils.sea.sea.Map object>

__init__(should_pack=True)

property jobs: List[schrodinger.application.desmond.cmj.Job]

get_prejobs() → List[schrodinger.application.desmond.cmj.Job]

Get the stage’s input jobs

add_jobs(jobs: Iterable[schrodinger.application.desmond.cmj.Job])

Add jobs to the stage’s job manager

add_job(job: schrodinger.application.desmond.cmj.Job)

Shortcut for add_jobs

get_output_jobs() → List[schrodinger.application.desmond.cmj.Job]

Get the stage’s output jobs

filter_jobs(**kwargs) → List[schrodinger.application.desmond.cmj.Job]

Return a list of jobs based on a matching a set of criteria given as arguments. Read JobManager.filter_jobs for available arguments.

describe()

migrate_param(param: schrodinger.utils.sea.sea.Map)

Subclasses can implement this to migrate params to provide backward compatibility with older msj files, ideally with a deprecation warning.

check_param()

push(job)

determine()

crunch()

This is where jobs of this stage are created. This function should be overriden by the subclass.

restart_subjobs(jobs)

Subclass should override this if it supports subjob restarting.

release(is_restarting=False)

Calls the ‘crunch’ method to generate new jobs objects and submits them to the ‘QUEUE’.

finalize_job(job: schrodinger.application.desmond.cmj.Job)

Call hook_captured_successful_job on any successful jobs and write a checkpoint

finalize_stage()

If the stage is done running, pack the stage, and if the stage is successful, continue to the next stage

prestage()

poststage()

hook_captured_successful_job(job)

time_stage()

pack_stage(force=False)

class schrodinger.application.desmond.cmj.JobManager

Bases: object

A class for managing a stage’s jobs. The jobs are stored in the _jobs list internally but should only be accessed by the jobs property or filter_jobs.

__init__()

property jobs: List[schrodinger.application.desmond.cmj.Job]

clear()

add_jobs(jobs: Iterable[schrodinger.application.desmond.cmj.Job])

Add the given jobs to the job manager but does not add duplicate jobs

submit_jobs(queue: schrodinger.application.desmond.queue.Queue)

filter_jobs(status=None, old=None, is_for_jc=None, is_output=None, failed=None, is_launchable=None, is_restartable=None, is_incomplete=None) → List[schrodinger.application.desmond.cmj.Job]

Get a subset of the job manager’s jobs. Each argument can either be None, to indicate no filtering on the property, or a list of acceptable values for the given argument’s property.

When passing in multiple arguments, the function returns jobs which satisfy all given criteria.

class schrodinger.application.desmond.cmj.StructureStageBase(*args, **kwargs)

Bases: schrodinger.application.desmond.cmj.StageBase

StructureStageBase can be used for stages that take in a path to a structure, apply some transformation, and then write out an updated structure.

__init__(*args, **kwargs)

crunch()

This is where jobs of this stage are created. This function should be overriden by the subclass.

run(jobname: str, input_fname: str) → Optional[str]

Parameters

• jobname – Jobname for this stage.

• input_fname – Filename for the input structure.

Returns

Filename for the output structure or None if there was an error generating the output.

class schrodinger.application.desmond.cmj.Engine(opt=None)

Bases: object

JOBBE = None

__init__(opt=None)

restore_stages(print_func=<function print_quiet>)

reset(opt)

Resets this engine with the command options.

boot_setup(base_dir=None)

Set up an Engine object, but do not start the queue.

Parameters

base_dir – Set to the path for the base_dir or None, the default, to use the cwd.

boot()

Boot the Engine and run the jobs.

run_set_family(max_stage_idx=None)

Re-run set_family for all task stages up to max_stage_idx.

handle_jobcontrol_message(stop=False)

cleanup(exit_code=0, skip_stage_check=False)

Parameters

skip_stage_check – Set to True to skip checking each stage to determine the exit code.

serialize(fh: BinaryIO)

serialize_bytes() → bytes

Return the binary contents of the serialized engine.

static deserialize(fh: BinaryIO)

write_checkpoint(fname=None, num_retry=10)

exception schrodinger.application.desmond.cmj.StopRequest

Bases: Exception

exception schrodinger.application.desmond.cmj.StopAndRestartRequest

Bases: Exception

exception schrodinger.application.desmond.cmj.ParseError

Bases: Exception

schrodinger.application.desmond.cmj.is_restartable_version(version_string)

schrodinger.application.desmond.cmj.is_restartable_build(engine)

schrodinger.application.desmond.cmj.build_stages(stage_list, out_fname=None, stage_state=[])

Build up the stages for the job, adding the initial Primer and final Concluder stages.

schrodinger.application.desmond.cmj.build_stagelinks(stage_list)

schrodinger.application.desmond.cmj.probe_checkpoint(fname, indent='')

schrodinger.application.desmond.cmj.escape_string(s)

schrodinger.application.desmond.cmj.append_stage(cmj_fname, stage_type, cfg_file=None, jobname=None, dir=None, compress=None, parameter={})

schrodinger.application.desmond.cmj.concatenate_relaxation_stages(raw)

Attempts to concatenate relaxation stages by finding all adjacent non-production simulate stages. If no concatenatable stages are found, None is returned. Otherwise, a new raw map with the relaxation simulate stages replaced with a single concatenate stage is returned.

Parameters

raw (sea.Map) – the raw map representing the MSJ

Returns

a new raw map representing the updated msj, or None.

Return type

sea.Map or None

schrodinger.application.desmond.cmj.get_concat_stages(stages, param_attr='')

Get a list of the stages that can be concatenated together, and the insertion point of the resulting concatenate stage. Stages can be concatenated if they are adjacent simulate stages with the same restraints, excluding the final production stage, which can be lambda hopping, replica exchange, or otherwise the last simulate stage.

Parameters

• stages (list of (sea.Map or stage.Stage)) – A list of objects representing multisim stages. For flexibility, these can be either maps or stages. For stages, a param attribute must be passed that will give the location of the param on the stage.

• param_attr (str) – optional name of the attribute of the objects param, in case of a stage.Stage object.

schrodinger.application.desmond.cmj.make_empty_restraints(existing='ignore') → schrodinger.utils.sea.sea.Map

schrodinger.application.desmond.cmj.get_restrain(sm: schrodinger.utils.sea.sea.Map) → schrodinger.utils.sea.sea.Sea

schrodinger.application.desmond.cmj.get_restraints(sm: schrodinger.utils.sea.sea.Map) → schrodinger.utils.sea.sea.Map

schrodinger.application.desmond.cmj.get_restraints_xor_convert_restrain(param: schrodinger.utils.sea.sea.Map) → schrodinger.utils.sea.sea.Map

Returns restrains or restrain (converted into restraints format) from the param. Raises ValueError if both are set.

Parameters

param – stage parameters

Returns

restraints block

schrodinger.application.desmond.cmj.restraints_incompatible(param: schrodinger.utils.sea.sea.Map, initial_param: schrodinger.utils.sea.sea.Map, has_permanent_restrain: bool)

Returns whether restraints parameters are compatible with switching during a concatenate stage. For compatibility the parameters has to differ from the initial ones by only a scaling factor (which can include zero). Furthermore, there can be no differences between restraints and initial restraints if permanent_restrain is truthy, as there is no way to selectively scale restraints.

Parameters

• param (sea.Map) – the param for a given stage

• initial_param (sea.Map) – parameters for the first stage

• has_permanent_restrain (bool) – whether or not there are restraints applied to all stages via the permanent_restraints mechanism

Returns

a message declaring how the restraints are incompatible, or an empty string if they are compatible

Return type

str

schrodinger.application.desmond.cmj.has_explicit_restraints(param: schrodinger.utils.sea.sea.Map)

Parameters

param – the param for a given stage

Returns

whether or not the restraints block has new or existing restraints

schrodinger.application.desmond.cmj.check_restrain_diffs(restrain, initial_restrain)

See if the differences between two restrain blocks are concatenation-compatible, meaning they are both sea.Map objects and differ only by a force constant.

Parameters

• restrain (sea.Map or sea.List) – the restrain block for a given stage

• initial_restrain (sea.Map or sea.List) – the restraints for the first stage

Returns

a message declaring how the restraints are incompatible, or an empty string if they are compatible

Type

str

schrodinger.application.desmond.cmj.msj2sea(fname, msj_content=None)

Parses a file as specified by ‘fname’ or a string given by ‘msj_content’ (if both are given, the former will be ignored), and returns a ‘sea.Map’ object that represents the stage settings with a structure like the following:

stage = [
   { <stage 1 settings> }
   { <stage 2 settings> }
   { <stage 3 settings> }
   ...
]

Each stage’s name can be accessed in this way: raw.stage[1].__NAME__, where ‘raw’ is the returned ‘sea.Map’ object.

schrodinger.application.desmond.cmj.msj2sea_full(fname, msj_content=None, pset='')

schrodinger.application.desmond.cmj.parse_msj(fname, msj_content=None, pset='')

sea.update_macro_dict must be called prior to calling this function.

schrodinger.application.desmond.cmj.write_msj(stage_list, fname=None, to_str=True)

Given a list of stages, writes out a .msj file of the name ‘fname’.

If ‘to_str’ is True, a string will be returned. The returned string contains the contents of the .msj file. If ‘to_str’ is False and not file name is provided, then this function does nothing.

schrodinger.application.desmond.cmj.write_sea2msj(stage_list, fname=None, to_str=True)

schrodinger.application.desmond.cmj.collect_inputfile(stage_list)

Returns a list of file names.

class schrodinger.application.desmond.cmj.AslValidator

Bases: object

CTSTR = 'hydrogen\n\n\n  1  0  0  0  1  0            999 V2000\n   -1.6976    2.1561    0.0000 C   0  0  0  0  0  0\nM  END\n$$$$\n'

CT = None

__init__()

is_valid(asl)

validate(a)

schrodinger.application.desmond.cmj.validate_asl_expr(stage_list)

Validates all ASL expressions that start with the “asl:” prefix.

schrodinger.application.desmond.cmj.reg_checking(name, func)