annotate alchemical_run/gmx_fep.xml @ 0:19d1d4c30402 draft

"planemo upload for repository https://github.com/galaxycomputationalchemistry/galaxy-tools-compchem/tools/free_energy commit b73986b131478d51e119de635fea5bd752c23b99"

<tool id="gmx_fep" name="Alchemical Run" version="2019.1">
    <description>Alchemical free energy simulations using gromacs</description> 
    <requirements>
         <requirement type="package" version="2019.1">gromacs</requirement>
    </requirements>
<command detect_errors="exit_code"><![CDATA[ 
    ln -s '$em_steep' ./em_steep.mdp &&
    ln -s '$nvt' ./nvt.mdp &&
    ln -s '$npt' ./npt.mdp &&
    ln -s '$md' ./md.mdp &&

    ln -s '$groin' ./morph.gro &&
    ln -s '$topin' ./morph.top &&

    #if $input_fep == 'perform':
      bash '$__tool_directory__/gmx_fep.sh' '$path.lambda' &>> '$report'
    #end if
    #if $input_fep == 'generate':
       mkdir -p input_files &&
       cp '$__tool_directory__/gmx_fep.sh'  input_files/ &&
       cp ./em_steep.mdp input_files/ &&
       cp ./nvt.mdp input_files/ &&
       cp ./npt.mdp input_files/ &&
       cp ./md.mdp input_files/ &&
       cp ./morph.gro input_files/ &&
       cp ./morph.top input_files/ &&
       tar cf input_files.tar input_files/
    #end if
    ]]></command>
     <configfiles>
         <configfile name="em_steep">
integrator               = steep
nsteps                   = $minstep
emtol                    = 100
emstep                   = 0.01
niter                    = 20
nbfgscorr                = 10
nstlog                   = 1
nstenergy                = 1
cutoff-scheme            = verlet
nstlist                  = 10
ns_type                  = grid
pbc                      = xyz
rlist                    = 1.2
coulombtype              = PME
rcoulomb                 = 1.2
vdwtype                  = cutoff
vdw-modifier             = potential-switch
rvdw-switch              = 1.0
rvdw                     = 1.2
DispCorr                  = EnerPres
fourierspacing           = 0.12
pme_order                = 6
ewald_rtol               = 1e-06
epsilon_surface          = 0
tcoupl                   = no
pcoupl                   = no
ld-seed                  = -1
gen-seed                 = $seed 
free_energy              = no
delta_lambda             = 0
calc_lambda_neighbors    = 1        
init-lambda-state        = %L%

#if $path.select_path == "global":
fep-lambdas              = $path.fep
#end if

#if $path.select_path in ["default1", "default2"]:
coul-lambdas             = $path.coul
vdw-lambdas              = $path.vdw
bonded-lambdas           = $path.bonded
#end if

sc-alpha                 = 0.5
sc-coul                  = no      
sc-power                 = 1
sc-sigma                 = 0.3
nstdhdl                  = 10

gen_vel                  = no
constraints              = none
         </configfile>
         <configfile name="nvt">
integrator               = sd       
tinit                    = 0
dt                       = $dt
nsteps                   = $nvtstep
nstcomm                  = 100
nstxout                  = 500
nstvout                  = 500
nstfout                  = 0
nstlog                   = 500
nstenergy                = 500
nstxout-compressed       = 0
cutoff-scheme            = verlet
nstlist                  = 20 
ns_type                  = grid
pbc                      = xyz
rlist                    = 1.2
coulombtype              = PME
rcoulomb                 = 1.2
vdwtype                  = cutoff
vdw-modifier             = potential-switch
rvdw-switch              = 1.0
rvdw                     = 1.2
DispCorr                  = EnerPres
fourierspacing           = 0.12
pme_order                = 6
ewald_rtol               = 1e-06
epsilon_surface          = 0
tc_grps                  = system
tau_t                    = 1.0
ref_t                    = $temperature 
Pcoupl                   = No
tau_p                    = 0.5
compressibility          = 4.5e-05
ref_p                    = $pressure
ld-seed                  = -1
gen-seed                 = $seed 
free_energy              = no
delta_lambda             = 0
calc_lambda_neighbors    = 1        
init-lambda-state        = %L%

#if $path.select_path == "global":
fep-lambdas              = $path.fep
#end if

#if $path.select_path in ["default1", "default2"]:
coul-lambdas             = $path.coul
vdw-lambdas              = $path.vdw
bonded-lambdas           = $path.bonded
#end if

sc-alpha                 = 0.5
sc-coul                  = no       
sc-power                 = 1
sc-sigma                 = 0.3
nstdhdl                  = 10
gen_vel                  = yes
gen_temp                 = 300

#if $constraints.cons == "no":
constraints              = none
#end if

#if $constraints.cons == "yes":
constraints              = $constraints.cons_type  
constraint-algorithm     = lincs
lincs-order              = $constraints.lincs_order
lincs-iter               = $constraints.lincs_iter
lincs-warnangle          = $constraints.lincs_warnangle
#end if
         </configfile>
         <configfile name="npt">
integrator               = sd    
tinit                    = 0
dt                       = $dt
nsteps                   = $nptstep
nstcomm                  = 100
nstxout                  = 500
nstvout                  = 500
nstfout                  = 0
nstlog                   = 500
nstenergy                = 500
nstxout-compressed       = 0
cutoff-scheme            = verlet
nstlist                  = 20
ns_type                  = grid
pbc                      = xyz
rlist                    = 1.2
coulombtype              = PME
rcoulomb                 = 1.2
vdwtype                  = cutoff
vdw-modifier             = potential-switch
rvdw-switch              = 1.0
rvdw                     = 1.2
DispCorr                  = EnerPres
fourierspacing           = 0.12
pme_order                = 6
ewald_rtol               = 1e-06
epsilon_surface          = 0
tc_grps                  = System
tau_t                    = 1.0
ref_t                    = $temperature 
Pcoupl                   = Berendsen 
tau_p                    = 0.5
compressibility          = 4.5e-05
ref_p                    = $pressure
ld-seed                  = -1
gen-seed                 = $seed  
free_energy              = no
delta_lambda             = 0
calc_lambda_neighbors    = 1        
init-lambda-state        = %L%

#if $path.select_path == "global":
fep-lambdas              = $path.fep
#end if

#if $path.select_path in ["default1", "default2"]:
coul-lambdas             = $path.coul
vdw-lambdas              = $path.vdw
bonded-lambdas           = $path.bonded
#end if

; Options for the decoupling
sc-alpha                 = 0.5
sc-coul                  = no       
sc-power                 = 1
sc-sigma                 = 0.3
nstdhdl                  = 10
gen_vel                  = no 

#if $constraints.cons == "no":
constraints              = none
#end if

#if $constraints.cons == "yes":
constraints              = $constraints.cons_type  
constraint-algorithm     = lincs
lincs-order              = $constraints.lincs_order
lincs-iter               = $constraints.lincs_iter
lincs-warnangle          = $constraints.lincs_warnangle
#end if
         </configfile>
         <configfile name="md">
integrator               = sd
bd-fric                  = 0
dt                       = $dt
nsteps                   = $mdstep
nstcomm                  = 100

nstxout                  = 10000  
nstvout                  = 0
nstfout                  = 0
nstlog                   = 10000
nstenergy                = 10000
nstxout-compressed       = 0

tcoupl                   = no
nsttcouple               = 10
tc_grps                  = System
tau_t                    = 1.0
ref_t                    = $temperature

#if $constraints.cons == "no":
constraints              = none
#end if

#if $constraints.cons == "yes":
constraints              = $constraints.cons_type  
constraint-algorithm     = lincs
lincs-order              = $constraints.lincs_order
lincs-iter               = $constraints.lincs_iter
lincs-warnangle          = $constraints.lincs_warnangle
#end if

comm-mode                = Linear

cutoff-scheme            = Verlet
nstlist                  = 10
ns_type                  = grid
pbc                      = xyz
rlist                    = 0.8

coulombtype              = PME
coulomb-modifier         = none
rcoulomb                 = 0.8
fourierspacing           = 0.10
pme_order                = 4
ewald_rtol               = 1.0E-5

vdwtype                  = cut-off
vdw-modifier             = none
rvdw                     = 0.8
DispCorr                 = AllEnerPres

pcoupl                   = Parrinello-Rahman
pcoupltype               = isotropic
tau_p                    = 2
compressibility          = 4.5e-5
ref_p                    = $pressure
refcoord-scaling         = com

gen-vel                  = no
continuation             = yes

ld-seed                  = -1
gen-seed                 = $seed 

free-energy              = yes
delta-lambda             = 0  ; do not use slow growth method
init-lambda-state        = %L%

#if $path.select_path == "global":
fep-lambdas              = $path.fep
#end if    

#if $path.select_path in ["default1", "default2"]:
coul-lambdas             = $path.coul
vdw-lambdas              = $path.vdw
bonded-lambdas           = $path.bonded
#end if

nstdhdl                  = 10
nstcalcenergy            = 10
calc-lambda-neighbors    = -1 
 
#if $feoptions.feop == "default":
sc-alpha                 = 0.5 
sc-coul                  = no  
sc-power                 = 1   
sc-r-power               = 6
sc-sigma                 = 0.3
couple-lambda0           = vdw-q
couple-lambda1           = none
couple-intramol          = no
#end if

#if $feoptions.feop == "modify":
sc-alpha                 = $feoptions.scalpha 
sc-coul                  = $feoptions.sccoul  
sc-power                 = $feoptions.scpower    
sc-r-power               = $feoptions.scrpower
sc-sigma                 = $feoptions.scsigma
couple-lambda0           = $feoptions.couplelambda0
couple-lambda1           = $feoptions.couplelambda1
couple-intramol          = $feoptions.coupleintramol 
#end if

dhdl-derivatives         = yes
dhdl-print-energy        = no
separate-dhdl-file       = yes
dh_hist_size             = 0
dh_hist_spacing          = 0.1

         </configfile>
    </configfiles>  
    <inputs>
        <param format="gro" name="groin" type="data" label="Structure (GRO) file" help="GRO input file with the merged structure."/>
        <param format="top" name="topin" type="data" label="Topology (TOP) file" help="TOP input file with the merged structure."/>
        <param name="minstep"  type="integer" value="10000" label="Minimization steps" help="Number of steps for each free energy window."/>
        <param name="nvtstep"  type="integer" value="500000" label="NVT equilibration steps" help="Number of MD steps for NVT equilibration for each free energy window."/>
        <param name="nptstep"  type="integer" value="500000" label="NPT equilibration steps" help="Number of MD steps for NPT equilibration for each free energy window."/>
        <param name="mdstep"   type="integer" value="1000000" label="MD (production) steps" help="Number of MD steps for production runs of each free energy window."/>
        <param name="seed"   type="integer" value="19880924" label="Seed" help="Seed to initialize random generator for random velocities."/>
        <param name="dt" type="float" value="0.001" label="Time step (ps)" help="Time step for integration."/>
        <conditional name="constraints">
            <param name="cons" type="select" label="Apply constraints to the ligands?" help="Constraints may be required to keep the ligands with alchemical states in the active site.">
                <option value="yes">Yes</option>
                <option value="no">No</option>
            </param>
            <when value="no"/>
            <when value="yes">
            <param name="cons_type" type="select" label="Constraints type" help="Convert all bonds to constraints, or only those containing hydrogen atoms">
                <option value="h-bonds" selected="true">H-bonds</option>
                <option value="all-bonds">All bonds</option>
            </param>
            <param name="lincs_order" type="integer" value="4" label="LINCS order" help="Accuracy of LINCS algorithm. For normal MD simulations an order of 4 usually suffices, 6 is needed for large time-steps with virtual sites or BD."/>
            <param name="lincs_iter" type="integer" value="1" label="LINCS iterations" help="Number of iterations to correct for rotational lengthening in LINCS. For normal runs a single step is sufficient."/>
            <param name="lincs_warnangle" type="integer" value="30" label="LINCS maximum angle" help="Maximum angle that a bond can rotate before LINCS will complain / [deg]"/>
            </when>
        </conditional>
        <conditional name="path">
            <param name="select_path" type="select" label="Select the FEP path">
                <option value="global">Use global lambda scaling</option>
                <option value="default1">Default option 1 (change a larger ligand to a smaller ligand)</option>
                <option value="default2">Default option 2 (change a smaller ligand to a larger ligand)</option>
            </param>
            <when value="global">
               <param name="lambda" type="text" value="2" label="Number of free energy windows"/>
               <param name="fep"  type="text" value="0.00 0.50 1.00" label="FEP Lambdas" help="Global scaling - values must be between 0 and 1."/>
            </when>
            <when value="default1">
               <param name="lambda" type="text" value="40" label="Number of free energy windows"/>
               <param name="coul"   type="text" value="0.00 0.11 0.22 0.33 0.44 0.56 0.67 0.78 0.89 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.000 1.00" label="Coulomb Lambdas (scaling electrostatics)" help="Values must be between 0 and 1."/>
               <param name="vdw"    type="text" value="0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.04 0.08 0.11 0.15 0.19 0.23 0.27 0.30 0.34 0.38 0.42 0.46 0.49 0.53 0.57 0.61 0.65 0.68 0.72 0.76 0.80 0.84 0.87 0.91 0.95 0.97 0.98 0.99 0.999 1.00" label="Van der Waals Lambdas (scaling vdw interactions)" help="Values must be between 0 and 1."/>
               <param name="bonded" type="text" value="0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.04 0.08 0.11 0.15 0.19 0.23 0.27 0.30 0.34 0.38 0.42 0.46 0.49 0.53 0.57 0.61 0.65 0.68 0.72 0.76 0.80 0.84 0.87 0.91 0.95 0.97 0.98 0.99 0.999 1.00" label="Bonded Lambdas (scaling torsion)" help="Values must be between 0 and 1."/> 
            </when>
            <when value="default2">
               <param name="lambda" type="text" value="40" label="Number of free energy windows"/>
               <param name="coul"   type="text" value="0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.000 0.00 0.11 0.22 0.33 0.44 0.56 0.67 0.78 0.89 1.00 " label="Coulomb Lambdas (scaling electrostatics)" help="Values must be between 0 and 1."/>
               <param name="vdw"    type="text" value="0.00 0.04 0.08 0.11 0.15 0.19 0.23 0.27 0.30 0.34 0.38 0.42 0.46 0.49 0.53 0.57 0.61 0.65 0.68 0.72 0.76 0.80 0.84 0.87 0.91 0.95 0.97 0.98 0.99 0.999 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00" label="Van der Waals Lambdas (scaling vdw interactions)" help="Values must be between 0 and 1."/>
               <param name="bonded" type="text" value="0.00 0.04 0.08 0.11 0.15 0.19 0.23 0.27 0.30 0.34 0.38 0.42 0.46 0.49 0.53 0.57 0.61 0.65 0.68 0.72 0.76 0.80 0.84 0.87 0.91 0.95 0.97 0.98 0.99 0.999 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00" label="Bonded Lambdas (scaling torsion)" help="Values must be between 0 and 1."/> 
            </when>
        </conditional>
        <conditional name="feoptions">
            <param name="feop" type="select" label="Free energy variables">
                <option value="default">Use default options</option>
                <option value="modify">Modify default options</option>
            </param>
            <when value="default"/>
            <when value="modify">
            <param name="scalpha" type="float" value="0.5" label="The soft-core alpha parameter (sc-alpha)" />
            <param name="scrpower" type="integer" value="6" label="The power of the radial term in the soft-core equation (sc-r-power)" />
            <param name="scpower" type="integer" value="1" label="The power for lambda in the soft-core function (sc-power)" />
            <param name="sccoul" type="text" value="no" label="Apply the soft-core free energy interaction transformation to the Columbic interaction of a molecule (sc-coul)? "/>
            <param name="scsigma" type="float" value="0.3" label="The soft-core sigma" />
            <param name="couplelambda0" type="text" value="vdw-q" label="Interactions at lambda=0" help="options are vdw-q, vdw, q, or none"/>
            <param name="couplelambda1" type="text" value="none" label="Interactions at lambda=1" help="options are vdw-q, vdw, q, or none"/>
            <param name="coupleintramol" type="text" value="no" label="Turn off intra-molecular interactions?" />
            </when>
        </conditional>
        <param name="temperature" type="float" value="300.0" label="Temperature /K" />
        <param name="pressure" type="float" value="1.0" label="Pressure /bar" />
        <param name="input_fep" type="select" label="Perform simulation or only generate input files?">
            <option value="perform">Perform simulation</option>
            <option value="generate">Only generate input files</option>
        </param>
    </inputs>
    <outputs>
        <data name="fepinpout" format="tar" from_work_dir="input_files.tar" label="Input files">
             <filter>input_fep == 'generate'</filter>
        </data>
        <data name="dataout" format="tar" from_work_dir="data.tar" label="TI/FEP data output">
             <filter>input_fep == 'perform'</filter>
        </data>
        <data name="trajout" format="tar" from_work_dir="traj.tar" label="Trajectories output">
             <filter>input_fep == 'perform'</filter>
        </data>
        <data name="report" format="txt" label="Report">
             <filter>input_fep == 'perform'</filter>
        </data>
    </outputs>
    <tests>
         <test>
            <param name="groin" value="morph.gro" ftype="gro"/>
            <param name="topin" value="morph.top" ftype="top"/>
            <param name="minstep" value="10"/>
            <param name="nvtstep" value="50"/>
            <param name="nptstep" value="50"/>
            <param name="mdstep" value="100"/>
            <param name="seed" value="19880924"/>
            <param name="cons" value="no"/>
            <param name="dt" value="0.001"/>
            <param name="path" value="global"/> 
            <param name="lambda" value="2"/>
            <param name="fep" value="0.00 0.50 1.00"/>
            <param name="temperature" value="300.0"/>
            <param name="fepop" value="default"/>
            <param name="input_fep" value="perform"/>
            <param name="pressure" value="1.0"/>
            <output name="dataout" file="TI_FEP_data_output.tar" compare="sim_size"/>
        </test>
        <test>
            <param name="groin" value="morph.gro" ftype="gro"/>
            <param name="topin" value="morph.top" ftype="top"/>
            <param name="minstep" value="10000"/>
            <param name="nvtstep" value="500000"/>
            <param name="nptstep" value="500000"/>
            <param name="mdstep" value="1000000"/>
            <param name="seed" value="123546"/>
            <param name="cons" value="yes"/>
            <param name="cons_type" value="h-bonds"/>
            <param name="lincs_order" value="4"/>
            <param name="lincs_iter" value="1"/>
            <param name="incs_warnangle" value="30"/>
            <param name="dt" value="0.002"/>
            <param name="path" value="default2"/> 
            <param name="lambda" value="40"/>
            <param name="coul" value="0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.000 0.00 0.11 0.22 0.33 0.44 0.56 0.67 0.78 0.89 1.00"/>
            <param name="vdw" value="0.00 0.04 0.08 0.11 0.15 0.19 0.23 0.27 0.30 0.34 0.38 0.42 0.46 0.49 0.53 0.57 0.61 0.65 0.68 0.72 0.76 0.80 0.84 0.87 0.91 0.95 0.97 0.98 0.99 0.999 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00"/>
            <param name="bonded" value="0.00 0.04 0.08 0.11 0.15 0.19 0.23 0.27 0.30 0.34 0.38 0.42 0.46 0.49 0.53 0.57 0.61 0.65 0.68 0.72 0.76 0.80 0.84 0.87 0.91 0.95 0.97 0.98 0.99 0.999 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00 1.00"/>
            <param name="temperature" value="300.0"/>
            <param name="fepop" value="default"/>
            <param name="input_fep" value="generate"/>
            <param name="pressure" value="1.0"/>
            <output name="fepinpout" file="Input_files.tar" compare="sim_size"/>
        </test>
    </tests>    
    <help><![CDATA[   
.. class:: infomark
 
**What it does**
        

    - This tool can run the alchemical free energy calculations using GROMACS.
    - For more details about alchemical free energy calculations see http://www.alchemistry.org/wiki/Main_Page
    - For details about GROMACS simulations see http://manual.gromacs.org/documentation/2019-rc1/user-guide/mdp-options.html

When you need to run the simulation outside Galaxy, you can generate and down load all the input files from this tool.

1. Simply download the output "Input files".
2. Untar it using tar -xvf  Galaxy3-\[Input_files\].tar
3. Run the bash script inside ./gmx_fep.sh {number of FEP windows}
   - Give the number of FEP windows as an argument.

This will generate input .MDP files and run all the steps for all the FEP windows iteratively.


_____


.. class:: infomark 

**Rules of Thumb for Intermediate States (taken from alchemistry.org)**  

    - These rules are not the end-all set and you should be familiar with why each one is suggested before just accepting them.  
    - Bonded terms can be modified/turned off linearly. This includes angle or bond force constants as well as unconstrained bond distances. 
    - Constrained bonds should not change length. There are free energy changes that cannot be ignored affiliated with this action. 
    - Maximize similarity between states by removing/decoupling as few atoms as possible. 
    - Do not open and close rings. This supersedes the previous rule. 
    - Statistical uncertainty between any neighboring states should be equal. Rather challenging to do, but it has been proven to have the lowest variance path if you can pull it off. 
    - Deleting or adding atoms should always be done with a soft core potential. 
    - Changes in parameters can be done linearly. 
    - All charge on atoms must be turned off prior to atomic repulsion. Otherwise you can get an infinite attractive potential and crash your simulation.  
    - Similarly for only changes in terms, it's generally more efficient to change electrostatic terms separate from Lennard-Jones terms. 
    - More states is better than fewer. Variance shrinks rapidly with number of states. You want the difference between intermediaries to be between 2-3 kBT 

Obviously you will be limited on CPU power. Fewer states also leads to more samples begin required from each state, so take this into account when deciding number of states as well.
However, for MBAR and TI, it can be shown that spreading samples across multiple states does not significantly affect the uncertainty, since for TI, each state contributes less to 
the total uncertainty, and in MBAR, data contributes to the statistical precision of states with similar values of lambda. 

Shape of the variance does not significantly change with number of atoms, only magnitude. More intermediates will still be required for a large number of atoms to reduce statistical noise.  
Charge should be maintained across all λ 

Simply having charged molecules is fine, but the net of the system should remain constant. If you must change the net charge, there are complicated ways to do so.

Short prototype simulations are recommended. Even as short as 100 ps, the prototypes can provide rough magnitude of variance estimates, 
although will likely under-predict the free energy as many configurations remain unsampled. 


_____


.. class:: infomark

**Input**

       - .GRO input 
       - .TOP input

_____

       
.. class:: infomark

**Output**

       - TI/FEP data
       - TI/FEP trajectory
       - Report

    ]]></help>
    <citations>
       <citation type="doi">10.1016/j.softx.2015.06.001</citation>
      <citation type="bibtex">@misc{alchemistrywiki, title={Alchemistry.org}, url={http://www.alchemistry.org/wiki/Main_Page}, journal={AlchemistryWiki}}
      </citation>
    </citations>
</tool>