From efe1efd58296716318348efc1db461895e54faf5 Mon Sep 17 00:00:00 2001 From: SwordJack <49801226+SwordJack@users.noreply.github.com> Date: Tue, 30 Apr 2024 02:17:39 -0500 Subject: [PATCH 1/5] Start the tutorial for geometry.equi_md_sampling API. --- .../geometry_equi_md_sampling.rst | 204 ++++++++++++++++++ 1 file changed, 204 insertions(+) create mode 100644 docs/source/sci_api_tutorial/geometry_equi_md_sampling.rst diff --git a/docs/source/sci_api_tutorial/geometry_equi_md_sampling.rst b/docs/source/sci_api_tutorial/geometry_equi_md_sampling.rst new file mode 100644 index 0000000..496cac1 --- /dev/null +++ b/docs/source/sci_api_tutorial/geometry_equi_md_sampling.rst @@ -0,0 +1,204 @@ +============================================== + Geometry: Equilibrium Molecular Dynamics Sampling +============================================== + +Briefs +============================================== + +This science API, named ``enzy_htp.geometry.equi_md_sampling``, +performs a production run of molecular dynamics simulation with the system equilibrated +by several short md simulations from the starting ``enzy_htp.structure.Structure`` class instance +(hereafter referred to as ``Structure`` instance). + +(Basically md_simulation() with preset steps) +min (micro) -> heat (NVT) -> equi (NPT) -> prod (NPT) + + +.. dropdown:: :fa:`eye,mr-1` Click to learn more about protein protonation + + Some supplementary information concerning MD simulation. + +Input/Output +============================================== + +**input**: A ``Structure`` instance (no matter it's a protein, polypeptite, or ligand). + +.. admonition:: How to obtain + + A ``Structure`` instance can be obtained by these `APIs `_. + + Note: Structure(s) with missing loops are not acceptable. + +**output**: A list of ``StructureEnsemble`` instances, i.e. a list trajectories for each replica in StructureEnsemble format. + +.. panels:: + + :column: col-lg-12 col-md-12 col-sm-12 col-xs-12 p-2 text-left + + .. image:: ../../figures/preparation_protonate_stru_dfd.svg + :width: 100% + :alt: preparation_remove_solvent + +Arguments +============================================== + +``stru`` + The input ``Structure`` instance (no matter it's a protein, polypeptite, or ligand). + + (See `Input/Output <#input-output>`_ section) + +``param_method`` + The ``MolDynParameterizer`` instance for parameterization, constructed by ``Parameterizer()``, which determines the engine. + + .. dropdown:: :fa:`eye,mr-1` Click to learn more about ``ph`` + + XXX + +``parallel_runs`` + The number of desired parallel runs of the steps. + + (Integer, optional, default ``3``) + +``parallel_method`` + The method to parallelize the multiple runs. + + (String, optional, default ``cluster_job``) + +``work_dir`` + The directory that contains all the MD input/intermediate/output files. + + (String, optional, default ``./MD``) + +``prod_time`` + The simulation time in production step (unit: ns) + + (Float, optional, default ``50.0``) + +``prod_temperature`` + The production temperature (unit: K). + + (Float, optional, default ``300.0``) + +``prod_constrain`` + The constrain applied in the production step. + + (``List[stru_cons.StructureConstraint]``, optional, default ``None``) + +``record_period`` + The simulation time period for recording the geom. (unit: ns) + + (Float, optional, default ``0.5``) + +``cluster_job_config`` + The config for cluster_job if it is used as the parallel method. + + (Dictionary, optional, default ``None``) + + .. dropdown:: :fa:`eye,mr-1` Click to learn more about ``ph`` + + XXX + +``cpu_equi_step`` + Whether to use CPUs for equilibrium step. + + (Boolean, optional, default ``None``) + + .. dropdown:: :fa:`eye,mr-1` Click to learn more about ``ph`` + + XXX + +``cpu_equi_job_config`` + The job config for the CPU equilibrium step if specified. + + (Dictionary, optional, default ``None``) + + .. dropdown:: :fa:`eye,mr-1` Click to learn more about ``ph`` + + XXX + +``job_check_period`` + The check period for wait_to_2d_array_end, functions when ``parallel_method='cluster_job'``. (unit: s) + + (Integer, optional, default ``210``) + + +Examples +============================================== + +Prepare the Input: Load Structure +---------------------------------------------- + +In order to make use of the API, we should have structure loaded. + +.. code:: python + + import enzy_htp.structure as struct + + sp = struct.PDBParser() + + pdb_filepath = "/path/to/your/structure.pdb" + stru = sp.get_structure(pdb_filepath) + +Execute API +---------------------------------------------- + +Use ``preparation.protonate_stru`` to protonate (i.e. add hydrogen atoms to) your structure. + +The simpliest use of ``protonate_stru`` is as follows. + Where the ``ph`` is set to ``7.0``, and ``protonate_ligand`` is set to ``True`` by default. + +.. code:: python + + from enzy_htp.preparation import protonate_stru + + protonate_stru(stru=stru) + +We can also customize the arguments passed to this function. + How much is your pH value? Customize ``ph``. + + Do you want to protonate your ligands? Customize ``protonate_ligand``. + +.. code:: python + + protonate.protonate_stru(stru=stru, ph=6.5, protonate_ligand=False) + +.. note:: + + This API modifies the ``Structure`` instance (what we passed as argument ``stru``) itself and does not return any value, i.e. return ``None``. + + Thus, if you write ``stru = protonate.protonate_stru(stru=stru)``, your ``stru`` will very unfortunately be assigned the value ``None``, so Please Don't Do This! + +Check the Output +---------------------------------------------- + +Let's try executing the API here and check if there's any changes taking place. + +.. panels:: + + :column: col-lg-12 col-md-12 col-sm-12 col-xs-12 p-2 text-left + + We choose the structure of a complex containing SARS-Cov-2 Main Protease + and Nirmatrelvir for example, whose solvent has been removed manually. + + Set ``ph=7.4`` (which is the pH value of human blood) and ``protonate_ligand=True`` (to protonate Nirmatrelvir). + + Now, we can go through the procedure. + + .. code:: python + + import enzy_htp.structure as struct + from enzy_htp.preparation import protonate + + sp = struct.PDBParser() + + pdb_filepath = "7si9_rm_water.pdb" # The structure of a complex containing SARS-Cov-2 Main Protease and Nirmatrelvir. + stru = sp.get_structure(pdb_filepath) + + print(stru.num_atoms) # 2402. + protonate.protonate_stru(stru=stru, ph=7.4, protonate_ligand=True) + print(stru.num_atoms) # 4751. + +We may notice that, after executing the API, the number of atoms (``num_atoms``) in the structure increased, +representing that the hydrogen atoms have been added to the structure. + +Author: Zhong, Yinjie \ No newline at end of file From 1c299fc4734736e5bc30bcf693bc97f88cffbe22 Mon Sep 17 00:00:00 2001 From: SwordJack <49801226+SwordJack@users.noreply.github.com> Date: Thu, 2 May 2024 04:10:14 -0500 Subject: [PATCH 2/5] The skeleton of geometry_equi_md_sampling and geometry_mol_dyn_param. --- docs/figures/geometry_equi_md_sampling.svg | 4 + docs/source/index.rst | 2 + .../source/sci_api_tutorial/assign_mutant.rst | 2 +- .../geometry_equi_md_sampling.rst | 141 +++++++++++------- .../geometry_mol_dyn_param.rst | 137 +++++++++++++++++ docs/source/sci_api_tutorial/single_point.rst | 18 +-- 6 files changed, 243 insertions(+), 61 deletions(-) create mode 100644 docs/figures/geometry_equi_md_sampling.svg create mode 100644 docs/source/sci_api_tutorial/geometry_mol_dyn_param.rst diff --git a/docs/figures/geometry_equi_md_sampling.svg b/docs/figures/geometry_equi_md_sampling.svg new file mode 100644 index 0000000..90f9243 --- /dev/null +++ b/docs/figures/geometry_equi_md_sampling.svg @@ -0,0 +1,4 @@ + + + +
Trajectories: List[StructureEnsemble]
equi_md_sampling
stru: Structure
param_method: MolDynParameterizer
 \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index de348e7..4fb03ff 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -55,6 +55,8 @@ This user guide contains: sci_api_tutorial/preparation_remove_solvent sci_api_tutorial/preparation_remove_hydrogens sci_api_tutorial/preparation_protonate_stru + sci_api_tutorial/geometry_mol_dyn_param + sci_api_tutorial/geometry_equi_md_sampling sci_api_tutorial/single_point sci_api_tutorial/add_missing_residues sci_api_tutorial/assign_mutant diff --git a/docs/source/sci_api_tutorial/assign_mutant.rst b/docs/source/sci_api_tutorial/assign_mutant.rst index 5fe9075..8918abc 100644 --- a/docs/source/sci_api_tutorial/assign_mutant.rst +++ b/docs/source/sci_api_tutorial/assign_mutant.rst @@ -1,5 +1,5 @@ ============================================== -Assign Mutant + Assign Mutant ============================================== Briefs diff --git a/docs/source/sci_api_tutorial/geometry_equi_md_sampling.rst b/docs/source/sci_api_tutorial/geometry_equi_md_sampling.rst index 496cac1..3ea408c 100644 --- a/docs/source/sci_api_tutorial/geometry_equi_md_sampling.rst +++ b/docs/source/sci_api_tutorial/geometry_equi_md_sampling.rst @@ -1,6 +1,6 @@ -============================================== - Geometry: Equilibrium Molecular Dynamics Sampling -============================================== +======================================================= +Geometry: Equilibrium Molecular Dynamics Sampling +======================================================= Briefs ============================================== @@ -10,32 +10,35 @@ performs a production run of molecular dynamics simulation with the system equil by several short md simulations from the starting ``enzy_htp.structure.Structure`` class instance (hereafter referred to as ``Structure`` instance). -(Basically md_simulation() with preset steps) -min (micro) -> heat (NVT) -> equi (NPT) -> prod (NPT) - - -.. dropdown:: :fa:`eye,mr-1` Click to learn more about protein protonation +.. dropdown:: :fa:`eye,mr-1` Click to learn more about **Equilibrium Molecular Dynamics Sampling** - Some supplementary information concerning MD simulation. + (Basically md_simulation() with preset steps) + min (micro) -> heat (NVT) -> equi (NPT) -> prod (NPT) Input/Output ============================================== -**input**: A ``Structure`` instance (no matter it's a protein, polypeptite, or ligand). +**input**: A ``Structure`` instance (no matter it's a protein, polypeptite, or ligand) and a ``MolDynParameterizer`` instance. -.. admonition:: How to obtain +.. admonition:: How to obtain ``Structure`` instance A ``Structure`` instance can be obtained by these `APIs `_. Note: Structure(s) with missing loops are not acceptable. +.. admonition:: How to compose ``MolDynParameterizer`` instance + + The ``MolDynParameterizer`` class is a parameterizer for Molecular Dynamics simulation. + + For detailed instructions, see `Molecular Dynamics Parameterizer `_. + **output**: A list of ``StructureEnsemble`` instances, i.e. a list trajectories for each replica in StructureEnsemble format. .. panels:: :column: col-lg-12 col-md-12 col-sm-12 col-xs-12 p-2 text-left - .. image:: ../../figures/preparation_protonate_stru_dfd.svg + .. image:: ../../figures/geometry_equi_md_sampling.svg :width: 100% :alt: preparation_remove_solvent @@ -50,9 +53,7 @@ Arguments ``param_method`` The ``MolDynParameterizer`` instance for parameterization, constructed by ``Parameterizer()``, which determines the engine. - .. dropdown:: :fa:`eye,mr-1` Click to learn more about ``ph`` - - XXX + (See `Input/Output <#input-output>`_ section) ``parallel_runs`` The number of desired parallel runs of the steps. @@ -82,10 +83,19 @@ Arguments ``prod_constrain`` The constrain applied in the production step. - (``List[stru_cons.StructureConstraint]``, optional, default ``None``) + (``List[structure_constraint.StructureConstraint]``, optional, default ``None``) + + .. dropdown:: :fa:`eye,mr-1` Click to learn more about ``StructureConstraint`` + + ``StructureConstraint`` is a class from ``enzy_htp.structure.structure_constraint`` module, defining the API for a constraint. + + Each primitive StructureConstraint defines exactly one type of interaction. + + StructureConstraints are meant to define flexible, non-package specific relationships that can be translated + in between different software packages. ``record_period`` - The simulation time period for recording the geom. (unit: ns) + The simulation time period for recording the geometry. (unit: ns) (Float, optional, default ``0.5``) @@ -94,25 +104,25 @@ Arguments (Dictionary, optional, default ``None``) - .. dropdown:: :fa:`eye,mr-1` Click to learn more about ``ph`` + .. dropdown:: :fa:`eye,mr-1` Click to learn more about ``cluster_job_config`` - XXX + The value of this argument depends on the settings of the supercomputer/cluster you use. ``cpu_equi_step`` Whether to use CPUs for equilibrium step. - (Boolean, optional, default ``None``) + (Boolean, optional, default ``False``) - .. dropdown:: :fa:`eye,mr-1` Click to learn more about ``ph`` + .. dropdown:: :fa:`eye,mr-1` Click to learn more about ``cpu_equi_step`` XXX ``cpu_equi_job_config`` - The job config for the CPU equilibrium step if specified. + The job config for the CPU equilibrium step if specified, functions when ``cpu_equi_step=False``. (Dictionary, optional, default ``None``) - .. dropdown:: :fa:`eye,mr-1` Click to learn more about ``ph`` + .. dropdown:: :fa:`eye,mr-1` Click to learn more about ``cpu_equi_job_config`` XXX @@ -147,26 +157,40 @@ Use ``preparation.protonate_stru`` to protonate (i.e. add hydrogen atoms to) you The simpliest use of ``protonate_stru`` is as follows. Where the ``ph`` is set to ``7.0``, and ``protonate_ligand`` is set to ``True`` by default. -.. code:: python - - from enzy_htp.preparation import protonate_stru +.. code:: python - protonate_stru(stru=stru) + import enzy_htp.structure as struct + + sp = struct.PDBParser() -We can also customize the arguments passed to this function. - How much is your pH value? Customize ``ph``. + pdb_filepath = "/path/to/your/structure.pdb" + stru = sp.get_structure(pdb_filepath) - Do you want to protonate your ligands? Customize ``protonate_ligand``. - -.. code:: python - - protonate.protonate_stru(stru=stru, ph=6.5, protonate_ligand=False) + from enzy_htp.core.clusters.accre import Accre + from enzy_htp.geometry import md_simulation, equi_md_sampling + from enzy_htp import interface + + amber_interface = interface.amber + + param_method = amber_interface.build_md_parameterizer() + cluster_job_config = { + "cluster" : Accre(), # + "res_keywords" : {"account" : "csb_gpu_acc", + "partition" : "turing"} + } + md_result = equi_md_sampling( + stru = stru, + param_method=param_method, + cluster_job_config=cluster_job_config, + job_check_period=10, + prod_time=0.5, + record_period=0.05) .. note:: - This API modifies the ``Structure`` instance (what we passed as argument ``stru``) itself and does not return any value, i.e. return ``None``. - - Thus, if you write ``stru = protonate.protonate_stru(stru=stru)``, your ``stru`` will very unfortunately be assigned the value ``None``, so Please Don't Do This! + Here, we execute MD simulation with a very short ``prod_time`` for example use. + + In real cases, the ``prod_time`` will usually be 30 ns ~ 110 ns. Check the Output ---------------------------------------------- @@ -177,28 +201,43 @@ Let's try executing the API here and check if there's any changes taking place. :column: col-lg-12 col-md-12 col-sm-12 col-xs-12 p-2 text-left - We choose the structure of a complex containing SARS-Cov-2 Main Protease - and Nirmatrelvir for example, whose solvent has been removed manually. - - Set ``ph=7.4`` (which is the pH value of human blood) and ``protonate_ligand=True`` (to protonate Nirmatrelvir). - - Now, we can go through the procedure. + Here, we use a well-preparaed complex containing SARS-Cov-2 Main Protease and Nirmatrelvir for example. .. code:: python - + import enzy_htp.structure as struct - from enzy_htp.preparation import protonate sp = struct.PDBParser() - pdb_filepath = "7si9_rm_water.pdb" # The structure of a complex containing SARS-Cov-2 Main Protease and Nirmatrelvir. + pdb_filepath = "7si9_rm_water_aH.pdb" stru = sp.get_structure(pdb_filepath) - print(stru.num_atoms) # 2402. - protonate.protonate_stru(stru=stru, ph=7.4, protonate_ligand=True) - print(stru.num_atoms) # 4751. + from enzy_htp.core.clusters.accre import Accre + from enzy_htp.geometry import md_simulation, equi_md_sampling + from enzy_htp import interface + + amber_interface = interface.amber + + param_method = amber_interface.build_md_parameterizer() + cluster_job_config = { + "cluster" : Accre(), # This is the interface for operating Vanderbilt University's Advanced Computational Cluster for Research and Education. + # You can customize a new class in `enzy_htp.core_cluster` folder so as + # to have it compatible to the computational cluster resources in your own institution(s). + "res_keywords" : { + "account" : "csb_gpu_acc", + "partition" : "a6000x4" + } + } + md_result = equi_md_sampling( + stru = stru, + param_method=param_method, + cluster_job_config=cluster_job_config, + job_check_period=10, + prod_time=0.5, + record_period=0.05) + + len(md_result) # 11. -We may notice that, after executing the API, the number of atoms (``num_atoms``) in the structure increased, -representing that the hydrogen atoms have been added to the structure. +We may notice that the MD simulation has generated 11 snapshots and stored in ``md_result``. Author: Zhong, Yinjie \ No newline at end of file diff --git a/docs/source/sci_api_tutorial/geometry_mol_dyn_param.rst b/docs/source/sci_api_tutorial/geometry_mol_dyn_param.rst new file mode 100644 index 0000000..c6fefe4 --- /dev/null +++ b/docs/source/sci_api_tutorial/geometry_mol_dyn_param.rst @@ -0,0 +1,137 @@ +=========================================================== +Geometry: Molecular Dynamics Parameter and Parameterizer +=========================================================== + +Briefs +============================================== + +This module, named ``enzy_htp._interface.handle_types.mol_dyn_parameterizer``, defines the interface of +``MolDynParameterizer`` and ``MolDynParameter`` as abstract classes for Molecular Dynamics Simulation (hereinafter called **MD Simulation**). + +We should use concrete class of ``MolDynParameterizer`` and ``MolDynParameter`` for specific MD Simulation engines. + +.. dropdown:: :fa:`eye,mr-1` Click to learn more about **MD Simulation engines** + + Currently, the only available engine for MD simulation is Amber. + + Thus, the only concrete class of ``MolDynParameterizer`` is ``AmberParameterizer``. + +Concrete Classes +============================================== + +AmberParameterizer +---------------------------------------------- + +This class is the MD simulation parameterizer for Amber. + +The recommended constructor of ``AmberParameterizer`` is ``enzy_htp._interface.amber_interface.AmberInterface.build_md_parameterizer`` + +Arguments for Constructor +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``force_fields`` + The list of force fields used for parameterization in Amber tleap format (default: ["leaprc.protein.ff14SB", "leaprc.gaff", "leaprc.water.tip3p"]) + + The argument `force_fields` should be a List[str] value or 'default', which is the only allowed string value for `force_fields`. + + (List[str], optional, default ``["leaprc.protein.ff14SB", "leaprc.gaff2", "leaprc.water.tip3p"]``) + +``charge_method`` + The method used for determine the atomic charge. + + This method is applied to parameterization of ligand, modified AA, and metal binding site. + + (String, optional, default ``AM1BCC``) + +``resp_engine`` (Works when ``charge_method="RESP"``.) + The engine for calculating the RESP charge. + + (String, optional, default ``g16``) + +``resp_lvl_of_theory`` (Works when ``charge_method="RESP"``.) + The level of theory for calculating the RESP charge + + (String, optional, default ``b3lyp/def2svp em=d3``) + +``ncaa_param_lib_path`` + The path of the non-CAA parameter library. + + This is where all generated NCAA (Non-Canonical Amino Acid) params goes to, which will prevent redundant generation of same NCAAs. + + (String, optional, default ``../ncaa_lib``, relative to the working directory) + + .. dropdown:: :fa:`eye,mr-1` Click to learn more about ``ncaa_param_lib_path`` + + Normally we suggest setting this to a directory that contains all workflows of a same wild-type/template enzyme. + * The NCAA-file correspondence is determined by + + 1. 3-letter name in the file; + 2. The file name (if 1 not exist); + + * Setting this to a path that is too general may cause conflict when different NCAAs have the same name. + + (e.g. Different tautomer or general res name like LIG) + +``force_renew_ncaa_parameter`` + Whether force renew the parameter files (frcmod etc.) for all NCAAs (Ligands, Modified Amino Acids, or Metals) + + (Boolean, optional, default ``False``) + +``ncaa_net_charge_engine`` + The engine the determines the net charge of NCAA if none is assigned in NCAA objects (Ligands, Modifed Residues, Metal Units) + + (String, optional, default ``PYBEL``) + +``ncaa_net_charge_ph`` + The pH value used in determining the net charge of NCAA. + + (Float, optional, default ``7.0``) + +``solvate_box_type`` + The shape of the solvation box. + + (String, optional, default ``oct``) + +``solvate_box_size`` + The size of the solvation box (Unit: Angstrom). + + (Float, optional, default ``10.0``) + +``gb_radii`` + The igb number - the effective GB radii used in the Generalized Born calculation. + This will influence the GB radii in the prmtop file and are only used implicit solvent calculations. + + (Integer, optional, default ``None``) + +``parameterizer_temp_dir`` + The temporary working directory that contains all the files generated by the AmberParameterizer. + + (String, optional, default ``__SCRATCH_DIR__/amber_parameterizer``) + + .. admonition:: About ``__SCRATCH_DIR__`` + + ``__SCRATCH_DIR__`` is a directory for scratch use, which can be defined by yourselves. + +``additional_tleap_lines`` + Handle for adding additional tleap lines before generating the parameters. + + (List[str], optional, default ``None``) + + +Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The simpliest use of the constructor is as follows. + +.. code:: python + + from enzy_htp import interface + amber_interface = interface.amber + + param_method = amber_interface.build_md_parameterizer() + + type(param_method) # + +We can learn from the output that an ``AmberParameterizer`` instance has been constructed by ``build_md_parameterizer`` function. + +Author: Zhong, Yinjie \ No newline at end of file diff --git a/docs/source/sci_api_tutorial/single_point.rst b/docs/source/sci_api_tutorial/single_point.rst index 937bd5a..36c75ea 100644 --- a/docs/source/sci_api_tutorial/single_point.rst +++ b/docs/source/sci_api_tutorial/single_point.rst @@ -108,16 +108,16 @@ Arguments .. dropdown:: :fa:`eye,mr-1` Click to see full argument explanations ``stru`` - the target molecule of the calculation represented as Structure() + The target molecule of the calculation represented as Structure() It can also be an ensemble of structures as StructureEnsemble() and in this case, each geometry in this ensemble will be calculated. (See `Input/Output <#input-output>`_ section) ``engine`` - the QM or QM/MM engine as a keyword. (See `Input/Output <#input-output>`_ section) + The QM or QM/MM engine as a keyword. (See `Input/Output <#input-output>`_ section) ``method`` - the level of theory of this calculation as a LevelOfTheory(). + The level of theory of this calculation as a LevelOfTheory(). This is used when there is only 1 region specified. (See `Input/Output <#input-output>`_ section) ``regions`` @@ -136,20 +136,20 @@ Arguments (See `Input/Output <#input-output>`_ section) ``capping_method`` - | the free valence capping method. (See `Capping Methods `_) - | default: ``"res_ter_cap"`` + The free valence capping method. (See `Capping Methods `_) + default: ``"res_ter_cap"`` ``embedding_method`` - | The embedding method of multiscale simulation. + The embedding method of multiscale simulation. This is used when more than 1 region is specified. Supported keywords: ["mechanical"] - | default: ``"mechanical"`` + default: ``"mechanical"`` ``parallel_method`` - | the method to parallelize the multiple runs when more + The method to parallelize the multiple runs when more than 1 geometry is in the input StructureEnsemble The execution will serial and locally if None is given. - | default: ``"cluster_job"`` + default: ``"cluster_job"`` ``cluster_job_config`` the config for cluster_job if it is used as the parallel method. From 2a6b7347a3d548cb9f37026073df7647fbcc0e69 Mon Sep 17 00:00:00 2001 From: SwordJack <49801226+SwordJack@users.noreply.github.com> Date: Thu, 2 May 2024 18:52:38 -0500 Subject: [PATCH 3/5] Modifications to geometry_equi_md_sampling and geometry_mol_dyn_param. --- docs/source/index.rst | 1 + .../geometry_equi_md_sampling.rst | 47 ++++++++++--------- .../geometry_mol_dyn_param.rst | 11 +++-- docs/source/sci_api_tutorial/preparation.rst | 14 ++++++ 4 files changed, 47 insertions(+), 26 deletions(-) create mode 100644 docs/source/sci_api_tutorial/preparation.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 4fb03ff..e08f8f0 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -52,6 +52,7 @@ This user guide contains: :caption: Tutorials sci_api_tutorial/how_to_assemble + sci_api_tutorial/preparation sci_api_tutorial/preparation_remove_solvent sci_api_tutorial/preparation_remove_hydrogens sci_api_tutorial/preparation_protonate_stru diff --git a/docs/source/sci_api_tutorial/geometry_equi_md_sampling.rst b/docs/source/sci_api_tutorial/geometry_equi_md_sampling.rst index 3ea408c..a707678 100644 --- a/docs/source/sci_api_tutorial/geometry_equi_md_sampling.rst +++ b/docs/source/sci_api_tutorial/geometry_equi_md_sampling.rst @@ -6,26 +6,36 @@ Briefs ============================================== This science API, named ``enzy_htp.geometry.equi_md_sampling``, -performs a production run of molecular dynamics simulation with the system equilibrated -by several short md simulations from the starting ``enzy_htp.structure.Structure`` class instance +performs a production run of Molecular Dynamics Simulation (hereinafter called **MD Simulation**) +with the system equilibrated by several short md simulations from the starting ``enzy_htp.structure.Structure`` class instance (hereafter referred to as ``Structure`` instance). .. dropdown:: :fa:`eye,mr-1` Click to learn more about **Equilibrium Molecular Dynamics Sampling** (Basically md_simulation() with preset steps) - min (micro) -> heat (NVT) -> equi (NPT) -> prod (NPT) + Minimalization (micro) -> Heating (NVT) -> Equilibrium (NPT) -> Production (NPT) Input/Output ============================================== -**input**: A ``Structure`` instance (no matter it's a protein, polypeptite, or ligand) and a ``MolDynParameterizer`` instance. +.. panels:: + + :column: col-lg-12 col-md-12 col-sm-12 col-xs-12 p-2 text-left + + .. image:: ../../figures/geometry_equi_md_sampling.svg + :width: 100% + :alt: preparation_remove_solvent + +**input**: A well-preparaed ``Structure`` instance (no matter it's a protein, polypeptite, or ligand) and a ``MolDynParameterizer`` instance. -.. admonition:: How to obtain ``Structure`` instance +.. admonition:: How to obtain well-preparaed ``Structure`` instance A ``Structure`` instance can be obtained by these `APIs `_. Note: Structure(s) with missing loops are not acceptable. + To prepare structure, please refer to these `APIs `_. + .. admonition:: How to compose ``MolDynParameterizer`` instance The ``MolDynParameterizer`` class is a parameterizer for Molecular Dynamics simulation. @@ -34,14 +44,6 @@ Input/Output **output**: A list of ``StructureEnsemble`` instances, i.e. a list trajectories for each replica in StructureEnsemble format. -.. panels:: - - :column: col-lg-12 col-md-12 col-sm-12 col-xs-12 p-2 text-left - - .. image:: ../../figures/geometry_equi_md_sampling.svg - :width: 100% - :alt: preparation_remove_solvent - Arguments ============================================== @@ -152,10 +154,7 @@ In order to make use of the API, we should have structure loaded. Execute API ---------------------------------------------- -Use ``preparation.protonate_stru`` to protonate (i.e. add hydrogen atoms to) your structure. - -The simpliest use of ``protonate_stru`` is as follows. - Where the ``ph`` is set to ``7.0``, and ``protonate_ligand`` is set to ``True`` by default. +Use ``geometry.equi_md_sampling`` to implement Equilibrium MD Simulation. .. code:: python @@ -174,9 +173,13 @@ The simpliest use of ``protonate_stru`` is as follows. param_method = amber_interface.build_md_parameterizer() cluster_job_config = { - "cluster" : Accre(), # - "res_keywords" : {"account" : "csb_gpu_acc", - "partition" : "turing"} + "cluster" : Accre(), # This is the interface for operating Vanderbilt University's Advanced Computational Cluster for Research and Education. + # You can customize a new class in `enzy_htp.core_cluster` folder so as + # to have it compatible to the computational cluster resources in your own institution(s). + "res_keywords" : { + "account" : "csb_gpu_acc", + "partition" : "turing" + } } md_result = equi_md_sampling( stru = stru, @@ -236,8 +239,8 @@ Let's try executing the API here and check if there's any changes taking place. prod_time=0.5, record_period=0.05) - len(md_result) # 11. + len(md_result) # 3. -We may notice that the MD simulation has generated 11 snapshots and stored in ``md_result``. +We may notice that the MD simulation has generated 3 snapshots and stored in ``md_result``. Author: Zhong, Yinjie \ No newline at end of file diff --git a/docs/source/sci_api_tutorial/geometry_mol_dyn_param.rst b/docs/source/sci_api_tutorial/geometry_mol_dyn_param.rst index c6fefe4..222b1ed 100644 --- a/docs/source/sci_api_tutorial/geometry_mol_dyn_param.rst +++ b/docs/source/sci_api_tutorial/geometry_mol_dyn_param.rst @@ -8,16 +8,19 @@ Briefs This module, named ``enzy_htp._interface.handle_types.mol_dyn_parameterizer``, defines the interface of ``MolDynParameterizer`` and ``MolDynParameter`` as abstract classes for Molecular Dynamics Simulation (hereinafter called **MD Simulation**). -We should use concrete class of ``MolDynParameterizer`` and ``MolDynParameter`` for specific MD Simulation engines. +In order to implement MD simulation, we need to apply the force fields to the complex, define to solvent box, etc., +which is the so-called "parameterization". However, different MD engines have different parameterization requirements. + +Thus, we use concrete class of ``MolDynParameterizer`` and ``MolDynParameter`` for specific MD Simulation engines. .. dropdown:: :fa:`eye,mr-1` Click to learn more about **MD Simulation engines** Currently, the only available engine for MD simulation is Amber. - Thus, the only concrete class of ``MolDynParameterizer`` is ``AmberParameterizer``. + Thus, the only concrete class of ``MolDynParameterizer`` at present is ``AmberParameterizer``. -Concrete Classes -============================================== +Concrete Implementations of ``MolDynParameterizer`` +======================================================= AmberParameterizer ---------------------------------------------- diff --git a/docs/source/sci_api_tutorial/preparation.rst b/docs/source/sci_api_tutorial/preparation.rst new file mode 100644 index 0000000..b4bcc99 --- /dev/null +++ b/docs/source/sci_api_tutorial/preparation.rst @@ -0,0 +1,14 @@ +============================================== +APIs that Help You Prepare Structures +============================================== + +Before performing simulation, we should have structures well-preparaed. +For example, we need to remove solvents and add hydrogen atoms to the structure complex. + +The following APIs can help you prepare your structures. + +- `Remove solvents `_ +- `Remove hydrogen atoms `_ +- `Protonate structure `_ + +Author: Zhong, Yinjie From 51fec9b52e881c872a0d6741e210c45d81f98614 Mon Sep 17 00:00:00 2001 From: SwordJack <49801226+SwordJack@users.noreply.github.com> Date: Thu, 2 May 2024 18:59:21 -0500 Subject: [PATCH 4/5] Fix some format issue in geometry_mol_dyn_param. --- docs/source/sci_api_tutorial/geometry_mol_dyn_param.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/source/sci_api_tutorial/geometry_mol_dyn_param.rst b/docs/source/sci_api_tutorial/geometry_mol_dyn_param.rst index 222b1ed..890ad75 100644 --- a/docs/source/sci_api_tutorial/geometry_mol_dyn_param.rst +++ b/docs/source/sci_api_tutorial/geometry_mol_dyn_param.rst @@ -66,6 +66,7 @@ Arguments for Constructor .. dropdown:: :fa:`eye,mr-1` Click to learn more about ``ncaa_param_lib_path`` Normally we suggest setting this to a directory that contains all workflows of a same wild-type/template enzyme. + * The NCAA-file correspondence is determined by 1. 3-letter name in the file; @@ -109,11 +110,11 @@ Arguments for Constructor ``parameterizer_temp_dir`` The temporary working directory that contains all the files generated by the AmberParameterizer. - (String, optional, default ``__SCRATCH_DIR__/amber_parameterizer``) + (String, optional, default ``{SCRATCH_DIR}/amber_parameterizer``) - .. admonition:: About ``__SCRATCH_DIR__`` + .. admonition:: About ``SCRATCH_DIR`` - ``__SCRATCH_DIR__`` is a directory for scratch use, which can be defined by yourselves. + ``SCRATCH_DIR`` is a directory for scratch use, which can be defined by yourselves. ``additional_tleap_lines`` Handle for adding additional tleap lines before generating the parameters. From 5a9b05c2fcb7a52c5d12d202aa5e04d5c8c5bb65 Mon Sep 17 00:00:00 2001 From: SwordJack <49801226+SwordJack@users.noreply.github.com> Date: Mon, 16 Jun 2025 20:13:29 -0500 Subject: [PATCH 5/5] Update the `equi_md_sampling` examples for ACCRE Rocky9. --- .../geometry_equi_md_sampling.rst | 30 +++++++++++-------- 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/docs/source/sci_api_tutorial/geometry_equi_md_sampling.rst b/docs/source/sci_api_tutorial/geometry_equi_md_sampling.rst index a707678..c35f837 100644 --- a/docs/source/sci_api_tutorial/geometry_equi_md_sampling.rst +++ b/docs/source/sci_api_tutorial/geometry_equi_md_sampling.rst @@ -68,7 +68,7 @@ Arguments (String, optional, default ``cluster_job``) ``work_dir`` - The directory that contains all the MD input/intermediate/output files. + The directory that saves all the MD input/intermediate/output files. (String, optional, default ``./MD``) @@ -172,13 +172,16 @@ Use ``geometry.equi_md_sampling`` to implement Equilibrium MD Simulation. amber_interface = interface.amber param_method = amber_interface.build_md_parameterizer() + cluster = AccreR9() # This is the interface for operating Vanderbilt University's Advanced Computational Clust + # You can customize a new class in `enzy_htp.core_cluster` folder so as + # to have it compatible to the computational cluster resources in your own institution(s). cluster_job_config = { - "cluster" : Accre(), # This is the interface for operating Vanderbilt University's Advanced Computational Cluster for Research and Education. - # You can customize a new class in `enzy_htp.core_cluster` folder so as - # to have it compatible to the computational cluster resources in your own institution(s). + "cluster" : cluster, "res_keywords" : { "account" : "csb_gpu_acc", - "partition" : "turing" + "partition" : "batch_gpu", + "nodes": "1", + "node_cores" : "nvidia_rtx_a6000:2", } } md_result = equi_md_sampling( @@ -222,16 +225,19 @@ Let's try executing the API here and check if there's any changes taking place. amber_interface = interface.amber param_method = amber_interface.build_md_parameterizer() + cluster = AccreR9() # This is the interface for operating Vanderbilt University's Advanced Computational Clust + # You can customize a new class in `enzy_htp.core_cluster` folder so as + # to have it compatible to the computational cluster resources in your own institution(s). cluster_job_config = { - "cluster" : Accre(), # This is the interface for operating Vanderbilt University's Advanced Computational Cluster for Research and Education. - # You can customize a new class in `enzy_htp.core_cluster` folder so as - # to have it compatible to the computational cluster resources in your own institution(s). + "cluster" : cluster, "res_keywords" : { "account" : "csb_gpu_acc", - "partition" : "a6000x4" + "partition" : "batch_gpu", + "nodes": "1", + "node_cores" : "nvidia_rtx_a6000:2", } } - md_result = equi_md_sampling( + md_result: List[StructureEnsemble] = equi_md_sampling( stru = stru, param_method=param_method, cluster_job_config=cluster_job_config, @@ -241,6 +247,6 @@ Let's try executing the API here and check if there's any changes taking place. len(md_result) # 3. -We may notice that the MD simulation has generated 3 snapshots and stored in ``md_result``. +We may notice that the MD simulation has generated 3 replicas and stored in ``md_result``. -Author: Zhong, Yinjie \ No newline at end of file +Author: Zhong, Yinjie