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.

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()¶

__init__()¶

__len__()¶: Returns the number of registered output files.

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

Parameters: type – either “file” and “dir”.

check(status)¶

get(tag)¶

log_file()¶

remove(filename)¶

set_struct_file(fname)¶

struct_file()¶

update_basedir(old_basedir, new_basedir)¶

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.cmj.StructureStageBase'>}¶

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.

NAME = 'generic'¶

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

RESTARTABLE = False¶

add_job(job: schrodinger.application.desmond.cmj.Job)¶: Shortcut for add_jobs

add_jobs(jobs: Iterable[schrodinger.application.desmond.cmj.Job])¶: Add jobs to the stage’s job manager

check_param()¶

count = 0¶

describe()¶

determine()¶

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.

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

get_output_jobs() → List[schrodinger.application.desmond.cmj.Job]¶: Get the stage’s output jobs

get_prejobs() → List[schrodinger.application.desmond.cmj.Job]¶: Get the stage’s input jobs

hook_captured_successful_job(job)¶

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

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.

pack_stage(force=False)¶

poststage()¶

prestage()¶

push(job)¶

release(is_restarting=False)¶: Calls the ‘crunch’ method to generate new jobs objects and submits them to the ‘QUEUE’.

restart_subjobs(jobs)¶: Subclass should override this if it supports subjob restarting.

stage_cls = {'generic': <class 'schrodinger.application.desmond.cmj.StructureStageBase'>}¶

stage_obj = {}¶

time_stage()¶

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

__init__(*args, **kwargs)¶

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception schrodinger.application.desmond.cmj.StopAndRestartRequest¶

Bases: Exception

__init__(*args, **kwargs)¶

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception schrodinger.application.desmond.cmj.ParseError¶

Bases: Exception

__init__(*args, **kwargs)¶

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

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)¶