Multisim Configuration (MSJ) Files

MSJ, .msj

  • Overview
  • Examples

The Multisim configuration file (MSJ), or job file, is what defines a Multisim workflow. The file consists of blocks that define a stage (in which at least one subjob is executed), generally adhering to the ARK format from D. E. Shaw Research. The only difference is that MSJ files allow for multiple blocks of the same name, so that a workflow may run multiple stages of the same type.

Note:

It is highly recommended that you familiarize yourself with the ARK syntax before working with MSJ files.

A stage begins with a label identifying the name of the stage, followed by braces enclosing parameters for that stage. This looks something like the following:

#an outline for a msj file.
#the first stage is usually task
first_stage_name {
   parameter1 = 3000.0
   parameter2 =  "this is a string"
   parameter3 = [ "list element 1" 2 "list element 3" ]
}
second_stage_name{
   parameter5 = 20
}

In the above example, Multisim would run first_stage_name, followed by second_stage_name, automatically passing in the relevant parameters.

Note:

The first stage in an MSJ file is usually the task stage. See Multisim Stages to see parameters for all stages.

Parameters can be set in a few different ways. The following list shows the order in which settings are applied: generally, later settings override earlier ones.

  1. Hard-coded defaults
  2. task { set_family[.family] = settings } affects the specified family after the current task stage. Here, family can be generic (all stages), desmond, or any stage name. Using a stage name changes settings for all subsequent instances of the stage.
  3. -c config_file specifies a default config file for the Desmond family.
  4. desmond-stage { cfg_file = cfg_file_name }.
  5. Stage settings.
  6. stage { backend = settings } if the stage supports backend settings.
  7. Settings made on the command line with -set.

See the Examples tab for a sample MSJ breakdown.

Sample MSJ breakdown

# Desmond standard NPT relaxation protocol
# All times are in the unit of ps.
# Energy is in the unit of kcal/mol.
task {
  task = "desmond:auto"
  set_family = {
    desmond = {
    checkpt.write_last_step = no
  }
}

simulate {
  title       = "Brownian Dynamics NVT, T = 10 K, small timesteps, and restraints on solute heavy atoms, 100ps""
  annealing   = off
  time        = 100
  timestep    = [0.001 0.001 0.003]
  temperature = 10.0
  ensemble = {
    class  = "NVT"
    method = "Brownie"
    brownie = {
      delta_max = 0.1
    }
  }
  restrain = {
    atom = "solute_heavy_atom"
    force_constant = 50.0
  }
}

simulate {
  effect_if   = [["==" "-gpu" "@*.*.jlaunch_opt[-1]"] 'ensemble.method = Langevin']
  title       = "NVT, T = 10 K, small timesteps, and restraints on solute heavy atoms, 12ps"
  annealing   = off
  time        = 12
  timestep    = [0.001 0.001 0.003]
  temperature = 10.0
  restrain    = { atom = solute_heavy_atom force_constant = 50.0 }
  ensemble    = {
    class  = NVT
    method = Berendsen
    thermostat.tau = 0.1
  }
  randomize_velocity.interval = 1.0
  eneseq.interval             = 0.3
  trajectory.center           = []
}

simulate {
  title       = "NPT, T = 10 K, and restraints on solute heavy atoms, 12ps"
  effect_if   = [["==" "-gpu" "@*.*.jlaunch_opt[-1]"] 'ensemble.method = Langevin']
  annealing   = off
  time        = 12
  temperature = 10.0
  restrain    = retain
  ensemble    = {
    class  = NPT
    method = Berendsen
    thermostat.tau = 0.1
    barostat.tau   = 50.0
  }
  randomize_velocity.interval = 1.0
  eneseq.interval             = 0.3
  trajectory.center           = []
}

simulate {
  title       = "NPT and restraints on solute heavy atoms, 12ps"
  effect_if   = [["@*.*.annealing"] 'annealing = off temperature = "@*.*.temperature[0][0]"'
                 ["==" "-gpu" "@*.*.jlaunch_opt[-1]"] 'ensemble.method = Langevin']
  time        = 12
  restrain    = retain
  ensemble    = {
    class  = NPT
    method = Berendsen
    thermostat.tau = 0.1
    barostat.tau   = 50.0
  }
  randomize_velocity.interval = 1.0
  eneseq.interval             = 0.3
  trajectory.center           = []
}

simulate {
  title       = "NPT and no restraints, 24ps"
  effect_if   = [["@*.*.annealing"] 'annealing = off temperature = "@*.*.temperature[0][0]"'
                 ["==" "-gpu" "@*.*.jlaunch_opt[-1]"] 'ensemble.method = Langevin']
  time        = 24
  ensemble    = {
    class  = NPT
    method = Berendsen
    thermostat.tau = 0.1
    barostat.tau = 2.0
  }
  eneseq.interval   = 0.3
  trajectory.center = solute
}

simulate {
  cfg_file = "jobname.cfg"
  jobname = "$MASTERJOBNAME"
  dir      = "."
  compress = ""
}
# Job launching command:
# $SCHRODINGER/utilities/multisim -VIEWNAME desmond_molecular_dynamics_gui.MDApp -JOBNAME jobname -HOST hostname -maxjob 1 -cpu 1 -m jobname.msj -c jobname.cfg -description "Molecular Dynamics" jobname.cms -mode umbrella -set stage[1].set_family.md.jlaunch_opt=[\"-gpu\"] -PROJ /home/user/multisim.prj -DISP append -o jobname-out.cms

This multisim workflow consists of eight stages. The first stage is the task stage, which specifies the type of job to be run and sets some common options for subsequent stages.

The second stage performs 100 ps of Brownian dynamics at 10 K to remove steric clashes similar to an energy minimization. All solute heavy atoms are restrained with a force constant of 50.0 kcal mol-1Å-1. The third stage performs 12 ps of molecular dynamics with the NVT ensemble at 10 K. A Langevin thermostat controls the temperature. The same restraints on the heavy atoms of the solute are applied again. The fourth stage is the same, except that the simulation is performed in the NPT ensemble at 1 atm pressure, controlled by a Langevin barostat. The fifth stage is skipped, as indicated by the keyword should_skip = true. The sixth stage is a 12 ps NPT simulation at the target temperature (300 K by default) and otherwise the same settings as the fourth stage. The seventh stage is a 24 ps NPT molecular dynamics simulation without restraints.

The output of stages one to seven is compressed into archives with the name jobname-X_out.tgz, where X is the stage number (1 to 7).

The eighth and last stage of this multisim workflow is the production stage. The parameters like time, temperature, pressure, etc. are specified in the Desmond .cfg file jobname.cfg. The job name is the same name as the master job name, so that the output files follow the pattern jobname.log, jobname.ene, etc.The option dir="." specifies that the stage's results are not stored in a separate directory, unlike the other stages. The option compress="" disables compression of the output files. This enables better inspection of the results after job has finished, for example, the trajectory.

At the end of the .msj file, a command is included that can be used to launch the multisim job from the command line. Several options, such as -VIEWNAME, -PROJ, and -DISP are only relevant for jobs submitted from Maestro.