schrodinger.application.matsci.equilibrium_md module

Equilibrium molecular dynamics classes/function shared by transport property calculations using Einstein and Green-Kubo methods.

Copyright Schrodinger, LLC. All rights reserved.

schrodinger.application.matsci.equilibrium_md.get_core_num()

Return the number of the cores specified by users. None means not specified.

Returns:the number of cores specified by users.
Return type:int or None
schrodinger.application.matsci.equilibrium_md.get_reserves_cores_state(options, check_runtype=True)

Return the state of reserves cores so that some python standard library functions can have access to all CPU resources.

Parameters:
  • options (bool) – If True, the FLAG_RUN_TYPE in the options is checked
  • check_runtype (bool) – If true, the FLAG_RUN_TYPE in the options is checked
Returns:

True, if reserves_cores_state should be set as True to allow some python function to utilize multiple CPUs.

Return type:

bool

schrodinger.application.matsci.equilibrium_md.get_files(filename, ext)

Get all the files with same extension, if ext is provided.

Parameters:
  • filename (str) – file to be located and returned
  • ext (str or None) – extension to search files of the same type
Return type:

list of str

Returns:

list of filenames with path

schrodinger.application.matsci.equilibrium_md.flatten_list(list_to_flatten)

Flatten [[a1, a2], [b1,]..] to [a1, a2, b1, ..].

Parameters:list_to_flatten (list) – [[a1, a2], [b1],…]; if [a1, a2, b1,…] is the input list, a copy will be returned.
Return type:list
Returns:[a1, a2.., b1, b2.., ..]
schrodinger.application.matsci.equilibrium_md.check_finite_molecules(struct, atom_ids=None)

Check whether the molecules in structure are finite.

Parameters:
  • struct (schrodinger.structure.Structure) – the structure whose molecules will be checked
  • atom_ids (set of int, list of int, list of list, or None) – molecules sharing atoms with this set will be checked. If None, all the molecules are checked.
Returns:

message if any molecules are infinite

Return type:

string or None

schrodinger.application.matsci.equilibrium_md.get_jdj(backend=None, gpu=False, smart_distribution=False)

Set up and return a ‘queue.JobDJ’ instance.

Parameters:
  • backend (schrodinger.job._Backend or None) – Backend handle. If None, a backend will be checked for.
  • gpu (bool) – whether the subjob needs gpu
  • smart_distribution (bool) – if True, keep one subjob on the master host
Returns:

the job control object to run jobs, processor number

Return type:

‘queue.JobDJ’, int

schrodinger.application.matsci.equilibrium_md.get_md_results(basename, opts, log, log_error, save_opts=None, gpu=False, smart_distribution=True)

From parsed options, setup and run md simulation.

Parameters:
  • basename (str) – basename for md simulation job
  • opts (Named tuple) – The parsed command line option
  • log (function) – log information
  • log_error (function) – log error information and exit
  • gpu (bool) – True indicates a GPU subhost
  • smart_distribution (bool) – turn on / off the smart_distribution
Return type:

str, str, str

Returns:

output cms, trj folder, and enegrp_dat

schrodinger.application.matsci.equilibrium_md.setup_md_job(name_base, md_opts, enegrp_opts=None, save_opts=None, command_dir=None)

Write the .msj file, form the command, figure out the output filenames, and register files to backend for molecular dynamics simulations.

Note: if command_dir is not None, please call this method inside the command_dir as the returned ocms_name doesn’t have command_dir in the file path.

Parameters:
  • name_base (base name for the md job) – str
  • md_opts – ‘type.SimpleNamespace’
  • enegrp_opts (this data struct has attributes: energy_groups for the list of keywords for desmond energy_groups, interval for output time interval in ps, start for the output starting time in ps. If None, no enegrp file is generated.) – ‘type.SimpleNamespace’ or None
  • save_opts (this data struct has boolean attributes to save files likes: msj, ene, multisim_log, ocms, log, trj, cfg, write_velocity, enegrp, last, autocorrelation_file, zip_outputs, viscosity_file. If None, use default settings to decide the files to be copied back.) – ‘type.SimpleNamespace’ or None
  • command_dir (this is the path from the job start dir to the subjob dir. The setup function is expected to run in the subjob setup stage, and thus the subjob dir should be passed. If there is only one master job (no sub dir), current dir is used. In addition, the returned file paths are the the basename, and then users need to form the full file path when they decide to run in subfolder or master folder directly.) – str
Return type:

‘type.SimpleNamespace’

Returns:

data struct with cmd command to submit md, output cms, trj folder, enegrp file, jobname

schrodinger.application.matsci.equilibrium_md.trim_parser_skip_md(options, extra=None)

If md is skipped, delete any options for setting up molecular dynamics simulation.

Parameters:
  • options (Parsed command options) – Named tuple
  • extra (extra flags to be deleted) – None or list of str
Return type:

options: Named tuple

Returns:

Parsed command options with no md flags

schrodinger.application.matsci.equilibrium_md.add_md_basic_argument(parser)
Parameters:parser (argparse.ArgumentParser) – The parser to add additional options
Return type:‘argparse._ArgumentGroup’
Returns:argparse ArgumentGroup with MD setting options

Add necessary parser arguments for setting up a MD simulation.

schrodinger.application.matsci.equilibrium_md.add_md_output_argument(parser, extra_options)

Add parser arguments to record output information for MD simulations.

Parameters:
  • parser (argparse.ArgumentParser) – The parser to add additional options
  • extra_options (extra options can be added according to these keywords) – list of str
Return type:

‘argparse._ArgumentGroup’

Returns:

argparse ArgumentGroup with MD output recording information

schrodinger.application.matsci.equilibrium_md.add_analysis_argument(parser, extra_options)

Add parser arguments for analysis.

Parameters:
  • parser (argparse.ArgumentParser) – The parser to add additional options
  • extra_options (extra options can be added according to these keywords) – list of str
Return type:

‘argparse._ArgumentGroup’

Returns:

argparse ArgumentGroup with analysis options

schrodinger.application.matsci.equilibrium_md.add_parser_opts(parser, final_prop, mid_prop, use_tau=True, extra_options=None)

Add all necessary parser arguments for setting up a MD simulation and optional arguments for certain green-kubo property calculation.

Parameters:
  • parser (argparse.ArgumentParser) – The parser for error information
  • final_prop (the final property needs to be calculated) – str
  • mid_prop (the property needs to be calculated before the final prop) – str
  • use_tau (Tau limits are added, if True) – bool
  • extra_options (extra options can be added according to these keywords) – None or list of str
Return type:

‘argparse._ArgumentGroup’, ‘argparse._ArgumentGroup’, ‘argparse._ArgumentGroup’

Returns:

argparse ArgumentGroups with setting options

schrodinger.application.matsci.equilibrium_md.check_options(opts, parser, option_flag, min_data_point, check_tau=True, check_gpu=False)

Validate the options.

Parameters:
  • opts (Named tuple) – The parsed command line options
  • parser (argparser.ArgumentParser) – parser to log error information
  • option_flag (str) – time interval is defined by this flag
  • min_data_point (int) – minimum required data point
  • check_tau (bool) – validate tau range against available time range
  • check_gpu (bool) – check GPU/CPU resource availability. For a remote host, -gpu flag requires a GPU host, and no -gpu flag requires a CPU HOST. For localhost and no job control, only check whether GPU resource is available when -gpu flag exists.
schrodinger.application.matsci.equilibrium_md.check_tau_options(opts, parser, option_flag, min_data_point)

Validate the Tau options.

Parameters:
  • opts (Named tuple) – The parsed command line options
  • parser (argparser.ArgumentParser) – parser to log error information
  • option_flag (str) – time interval is defined by this flag
  • min_data_point (int) – minimum required data point
class schrodinger.application.matsci.equilibrium_md.EquilibriumMdBase(icms_name, log=None, log_error=None)

Bases: object

This is a base class for equilibrium MD subclass, and should be not be instantiated directly.

__init__(icms_name, log=None, log_error=None)
Parameters:
  • icms_name (cms input file) – str
  • log (func to log info) – callable func
  • log_error (func to log error and exit) – callable func
checkSetTimeInterval(time_intervals=None)

Time interval must be the same for all trajectery.

Parameters:time_intervals (list or None) – time intervals between every two frames.
checkConstantVol(allow_npt=True)

Calculate volume and check whether it changes.

Parameters:allow_npt (bool) – allow volume to change, if True
calDensity()

Caluate the average system density.

savePropAndCms(cms_out=None)

Save properties to cms model, delete trj information if needed, and write out cms file.

Parameters:cms_out (str) – name of the output cms.
class schrodinger.application.matsci.equilibrium_md.TrjBase(icms_name, log=None, log_error=None)

Bases: schrodinger.application.matsci.equilibrium_md.EquilibriumMdBase

This is a base class for equilibrium MD subclass that uses trajectory, and should be not be instantiated directly.

readTrj(make_whole=False)

Read trj frames from trj folder.

Parameters:make_whole (bool) – if True, bond across PBCs are fixed so that two bonded particles won’t be on opposite sides of the system
trajFrames(make_whole=False)

Fix pbc bonds (if needed), yield the trajectory frame, and garbage-collect to release the occupied memory.

Parameters:make_whole (bool) – if True, bond across PBCs are fixed so that two bonded particles won’t be on opposite sides of the system
Return type:schrodinger.application.desmond.packages.traj.frame
Returns:a trajectory frame
checkTau(total_trj_frame_num, min_tau_data_point)

Check whether trj frame number is large enough.

Parameters:
  • total_trj_frame_num (number of total data point) – int
  • min_tau_data_point (minimum requested data) – int
checkVel()

Check whether each frame contains velocity information.

__init__(icms_name, log=None, log_error=None)
Parameters:
  • icms_name (cms input file) – str
  • log (func to log info) – callable func
  • log_error (func to log error and exit) – callable func
calDensity()

Caluate the average system density.

checkConstantVol(allow_npt=True)

Calculate volume and check whether it changes.

Parameters:allow_npt (bool) – allow volume to change, if True
checkSetTimeInterval(time_intervals=None)

Time interval must be the same for all trajectery.

Parameters:time_intervals (list or None) – time intervals between every two frames.
savePropAndCms(cms_out=None)

Save properties to cms model, delete trj information if needed, and write out cms file.

Parameters:cms_out (str) – name of the output cms.
class schrodinger.application.matsci.equilibrium_md.MixInBlockStd

Bases: object

This is a base class for dividing long simulation into blocks to get standard deviation, and should be not be instantiated directly.

checkBlockTau(total_step_num, min_tau_data_point)

Chech whether there are minimum data points between Tau start and end.

Parameters:
  • total_step_num (number of total data point) – int
  • min_tau_data_point (minimum requested data) – int
__init__

Initialize self. See help(type(self)) for accurate signature.

class schrodinger.application.matsci.equilibrium_md.SingleMDJob(jobname, md_opts, enegrp_opts, save_opts, command_dir='.')

Bases: schrodinger.application.matsci.jaguarworkflows.RobustSubmissionJob

Job class to submit a molecular dynamics simulation.

__init__(jobname, md_opts, enegrp_opts, save_opts, command_dir='.')
Parameters:
  • jobname (str) – The basename for the job
  • md_opts ('SimpleNamespace') – molecular dynamics options
  • enegrp_opts ('SimpleNamespace') – enegrp options
  • save_opts ('SimpleNamespace') – files to save
  • command_dir (str) – the job launch dir
setup()

Over write parent class method.

addFinalizer(function, run_dir=None)

Add a function to be invoked when the job completes successfully.

See also the add_multi_job_finalizer function.

addGroupPrereq(job)

Make all jobs connected to job prerequisites of all jobs connected to this Job.

addPrereq(job)

Add a job that is an immediate prerequisite for this one.

cancelSubmitted()

If the job is still in the ‘submitted’ state, cancel it, purge the jobrecord and set the job handle to None.

Return True if this was successful, False otherwise.

Return type:bool
doCommand(host, local, use_async=True)

Launch job on specified host using jobcontrol.launch_job().

Parameters:
  • host (str) – Host on which the job will be executed.
  • local (bool) – Removed in JOB_SERVER.
  • use_async (If True, do not block JobDJ for launching.) – bool
finalize()

Clean up after a job successfully runs.

genAllJobs(seen=None)

A generator that yields all jobs connected to this one.

genAllPrereqs(seen=None)

A generator that yields all jobs that are prerequisites on this one.

getCommand()

Return the command used to run this job.

Return type:list(str)
getCommandDir()

Return the launch/command directory name. If None is returned, the job will be launched in the current directory.

Return type:str
getJob()

Return the job record as a schrodinger.job.jobcontrol.Job instance.

Returns None if the job hasn’t been launched.

getJobDJ()

Return the JobDJ instance that this job has been added to.

getPrereqs()

Return a set of all immediate prerequisites for this job.

getStatusStrings()

Return a tuple of status strings for printing by JobDJ.

The strings returned are (status, jobid, name, host).

hasStarted()

Returns True if this job has started (not waiting)

init_count = 0
isComplete()

Returns True if this job finished successfully

kill()

Send kill request to jobcontrol managed job

maxFailuresReached(msg)

Print an error summary, including the last 20 lines from each log file in the LogFiles list of the job record.

postCommand()

A method to restore things to the pre-command state.

preCommand()

A method to make pre-command changes, like cd’ing to the correct directory to run the command in.

retryFailure(max_retries=0)

Determine if the job should be retried or not. This overwrites the parent method to not retry jobs that have a status of “died” as that will indicate that Jaguar failed, which it almost certainly will again.

Parameters:max_retries (int) – The queue’s max_retries parameter
Return type:bool
Returns:True if the job should be retried, False if not
run(*args, **kwargs)

Run the job.

The steps taken are as follows:
  1. Execute the preCommand method for things like changing the working directory.
  2. Call the doCommand to do the actual work of computation or job launching.
  3. Call the postCommand method to undo the changes from the preCommand that need to be undone.
runsLocally()

Return True if the job runs on the JobDJ control host, False if not. Jobs that run locally don’t need hosts.

There is no limit on the number of locally run jobs.

state

Return the current state of the job.

Note that this method can be overridden by subclasses that wish to provide for restartability at a higher level than unpickling BaseJob instances. For example, by examining some external condition (e.g. presence of output files) the state DONE could be returned immediately and the job would not run.

update(use_async=True)

Checks for changes in job status, and updates the object appropriately (marks for restart, etc).

Parameters:use_async (bool) – If True, use asynchronous API for downloading
Raises:RuntimeError – if an unknown Job Status or ExitStatus is encountered.
usesJobServer()

Detect, by looking at the jobId, whether this job uses a job server. Since the jobId is only set once, cache the answer (_uses_job_server) once it is established.

class schrodinger.application.matsci.equilibrium_md.MultiDriver(opts, jobname_base, logger=None)

Bases: object

Class to fire off multiple subjobs.

__init__(opts, jobname_base, logger=None)
Parameters:
  • opts (Named tuple) – The parsed command line options
  • jobname_base (str) – base name of this job
  • logger (logging.Logger) – The logger for this builder
run()

Run multiple calculation and perform ensemble average.

convertMultiToOne()

Convert data from files from multiple subjobs into one single file.

loadDataFromAllInOneFile()

Set the all-in-one file based on user input.

setUpQue()

Setup job queue.

initiateAndAddMdJobs(SingleMDJob=<class 'schrodinger.application.matsci.equilibrium_md.SingleMDJob'>, has_enegrp=False, additional_save_info=None, **kwargs)

Construct options, and initiate SingleMDJob jobs, and added them to jobdj.

Parameters:
  • SingleMDJob ('queue.JobControlJob') – instantiate this class to an object that can be added to jobdj
  • has_enegrp (bool) – if None, no enegrp file is generated.
  • additional_save_info ('types.SimpleNamespace') – additional information on what files to be copied back.
log(msg, **kwargs)

Add a message to the log file

Parameters:msg (str) – The message to log

Additional keyword arguments are passed to the textlogger.log_msg function

log_error(msg)

Add a message to the log file and exit with an error code

Parameters:msg (str) – The message to log
runSubjobs()

Run molecular dynamics jobs and Summarize the status of the runs.