Update docs

_build/_sources/cli_tutorials.rst.txt

@@ -0,0 +1,22 @@
+CLI Tutorials
+==============
+
+maize-biosimspace provides a large number of nodes for performing common operations such as parameterisation, minimisation, equilibration, production molecular
+dynamics, and alchemical free energy calculations. Nodes are generally engine-specific as maize requires that nodes have a list of ``required_callables`` whose presence
+in the environment is checked before the node is run. To see a list of all available nodes, type ``bss_`` and hit tab to list them. To see the options for each, pass
+pass the ``-h`` flag e.g.
+
+.. code-block:: bash
+
+   bss_parameterise -h
+
+These tutorials give specific examples of using BioSimSpace maize nodes to run production molecular dynamics, to create equilibrated systems starting from unparameterised
+input structures, and to run absolute binding free energy calculations starting from a protein pdb and an sdf file containing multiple ligands.
+
+.. toctree::
+   :maxdepth: 1
+
+   tutorial_cli_production_md
+   tutorial_cli_system_preparation
+   tutorial_cli_abfe
+

_build/_sources/configuration.rst.txt

@@ -0,0 +1,22 @@
+Configuration
+-------------
+For a detailed guide to configuring Maize, please see the `maize documentation <https://molecularai.github.io/maize/docs/userguide.html#configuring-workflows>`_
+and the `maize-contrib documentation <https://molecularai.github.io/maize-contrib/docking.html#Configuration>`_.
+
+By default, Maize looks for `$XDG_CONFIG_HOME/maize.toml` (`~/.config/maize.toml`) for configuration information. To set up Maize to run through slurm, run
+
+.. code-block:: bash
+
+   export XDG_CONFIG_HOME=~/.config
+
+Then create `~/.config/maize.toml` containing the following
+
+.. code-block:: toml
+
+  system = "slurm"  # Can be one of {'cobalt', 'flux', 'local', 'lsf', 'pbspro', 'rp', 'slurm'}
+  max_jobs = 100  # The maximum number of jobs that can be submitted by a node at once
+  queue = "gpu" #CHANGEME to your desired GPU queue
+  launcher = "srun"  # The launcher to use for the command, usually one of {'srun', 'mpirun', 'mpiexec'}
+  walltime = "24:00:00"  # Job walltime limit, shorter times may improve queueing times
+
+Now when you execute a Maize workflow, it will submit jobs to the slurm scheduler.

_build/_sources/index.rst.txt

@@ -10,9 +10,18 @@ maize-biosimspace
 .. toctree::
    :hidden:
    :maxdepth: 1
-   :caption: Examples
+   :caption: Setup
 
-   production-md
+   installation
+   configuration
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+   :caption: Tutorials
+
+   cli_tutorials
+   python_tutorials
 
 .. toctree::
    :hidden:
@@ -29,37 +38,37 @@ maize-biosimspace
    Steps <https://molecularai.github.io/maize/docs/steps>
    Maize <https://molecularai.github.io/maize>
 
-Installation
-------------
-To install, simply clone this repository and run:
+Quick Start
+-----------
+Clone the repository and install:
 
 .. code-block:: bash
 
+   git clone https://github.com/fjclark/maize-biosimspace.git
+   cd maize-biosimspace
    mamba env create -f env-users.yml
    mamba activate maize-biosimspace
    pip install --no-deps ./
 
-If you want to keep up-to-date with the latest changes to the core, clone `maize <https://github.com/MolecularAI/maize>`_, switch to the directory, and run (in the same conda environment):
+Ensure that the required AMBER, GROMACS, and NAMD executables are available in your environment if you plan to use the relevant nodes.
 
-.. code-block:: bash
+Many maize-biosimspace workflows will now be available through CLIs. Try typing `bss_` and hitting tab to list them. To see the options for each, type e.g.
 
-   pip install --no-deps ./
-
-If you plan on developing, you should use ``env-dev.yml`` instead and use the ``-e`` flag for ``pip``.
+.. code-block:: bash
 
-Configuration
--------------
-Each step documentation will contain information on how to setup and run the node, as well as install the required dependencies. Dependencies can be managed in several ways, depending on the node and workflow you are running:
+   bss_parameterise -h
 
-* Through a ``module`` system:
+To run production 0.1 ns of production MD on a protein-ligand complex using GROMACS, dumping all of the intermediate files to the current directory:
 
-  Specify a module providing an executable in the ``config.toml`` (see `Configuring workflows <https://molecularai.github.io/maize/docs/userguide.html#config-workflow>`_). This module will then be loaded in the process running the node.
+.. code-block:: bash
 
-* With a separate python environment:
+   mkdir gmx_md_example
+   cd gmx_md_example
+   cp ../tests/data/complex.* .
+   bss_production_gromacs --inp complex.prm7 complex.rst7 --runtime 0.1 --save_name gmx_md_out --dump_to .
 
-  Some nodes will require custom python environments that are likely to be incompatible with the other environments. In those cases, the node process can be spawned in a custom environment. Note that this environment must still contain *maize*.
+This will run locally. To configure maize nodes to run through a scheduler such as slurm, see :doc:`configuration`.
 
-* By specifying the executable location and possibly script interpreter. This can also be accomplished using ``config.toml`` (see `Configuring workflows <https://molecularai.github.io/maize/docs/userguide.html#config-workflow>`_).
 
 
 Indices and tables

_build/_sources/installation.rst.txt

@@ -0,0 +1,29 @@
+Installation
+------------
+For a basic installation, simply clone this repository and run:
+
+.. code-block:: bash
+
+   git clone https://github.com/fjclark/maize-biosimspace.git
+   cd maize-biosimspace
+   mamba env create -f env-users.yml
+   mamba activate maize-biosimspace
+   pip install --no-deps ./
+
+Ensure that the required AMBER, GROMACS, and NAMD executables are available in your environment if you plan to use the relevant nodes.
+
+If you want to keep up-to-date with the latest changes to the core, clone `maize <https://github.com/MolecularAI/maize>`_, switch to the directory, and run (in the same conda environment):
+
+.. code-block:: bash
+
+   pip install --no-deps ./
+
+If you plan on developing, you should use ``env-dev.yml`` instead and use the ``-e`` flag for ``pip``.
+
+.. code-block:: bash
+
+   git clone https://github.com/fjclark/maize-biosimspace.git
+   cd maize-biosimspace
+   mamba env create -f env-dev.yml
+   mamba activate maize-biosimspace
+   pip install -e --no-deps ./

_build/_sources/python_tutorials.rst.txt

@@ -0,0 +1,13 @@
+Python Tutorials
+================
+
+Nodes and subgraphs from maize-biosimspace can be combined into more complex
+workflows through python, and can benefit from other nodes available through
+maize-contrib. You can also use pre-made maize-biosimspace workflows through python
+to gain fuller control over all the options (compared to the CLI) and to write
+more reusable scripts.
+
+.. toctree::
+   :maxdepth: 1
+
+   tutorial_python_production

_build/_sources/tutorial_cli_abfe.rst.txt

@@ -0,0 +1,55 @@
+Absolute Binding Free Energy Calculations
+=========================================
+
+Here, we'll run a quick absolute binding free energy calculation for benzene bound to T4 Lysozyme. For this, we'll
+use the ``bss_abfe_multi_isomer`` workflow through its CLI, which requires only an SDF file containing all required
+ligands, and the pdb of the protein. Check the options with
+
+.. code-block:: bash
+
+   bss_abfe_multi_isomer -h
+
+Copy over the required input:
+
+.. code-block:: bash
+
+   mkdir bss_abfe_example
+   cd bss_abfe_example
+   cp ../tests/data/benzene.sdf .
+   cp ../tests/data/t4l.pdb .
+
+Now, let's run a relatively very short (but still fairly expensive)
+ABFE calculation with 2 replicates:
+
+.. code-block:: bash
+
+   bss_abfe_multi_isomer --lig_sdfs_file benzene.sdf \
+                         --protein_pdb benzene.t4l \
+                         --ligand_force_field gaff2 \
+                         --protein_force_field ff14SB \
+                         --abfe_timestep 4 \
+                         --abfe_n_replicates 2 \
+                         --abfe_runtime 0.1 \
+                         --abfe_runtime_generate_boresch_restraint 0.1 \
+                         --prep_runtime_restrained_npt 0.05 \
+                         --prep_runtime_unrestrained_npt 0.05 \
+                         --abfe_estimator TI \
+                         --results_file_name abfe_out \
+
+The ``abfe_out`` file should show results around -4 kcal / mol.
+
+Running through the command line with this many arguments is unweildy,
+and some options aren't available through the CLI (for example, the lambda
+spacing). It's likely a better option to write a quick script - using the
+pre-made workflow directly in python - simply import the workflow factory
+, customise the options, and run (all in a python script):
+
+.. code-block:: python
+   
+   from maize.graphs.exs.biosimspace.afe import getabfe_multi_isomer_workflow
+   workflow = getabfe_multi_isomer_workflow()
+
+   # Set workflow options...
+
+   # Run
+   workflow.execute()

_build/_sources/tutorial_cli_production_md.rst.txt

@@ -0,0 +1,30 @@
+Production Molecular Dynamics
+=============================
+
+Here, we'll run production molecular dynamics on a protein-ligand complex. To check the available production CLIs, type ``bss_production`` and hit tab:
+
+.. code-block:: bash
+
+   bss_production_gromacs     bss_production_pmemd       bss_production_pmemd_cuda  bss_production_sander      bss_production_somd     
+
+We'll pick gromacs. To check the available arguments and defaults, run
+
+.. code-block:: bash
+
+   bss_production_gromacs -h
+
+We'll run a quick 0.1 ns of production molecular dynamics on the protein-ligand complex included with `maize-biosimspace` for testing. We'll specify the output 
+name to be ``gmx_md_out`` and we'll save all of the intermediate files (including input scripts, logs, and trajectory files) to a subdirectory in the current
+working directory by specifying ``--dump_to .``
+
+.. code-block:: bash
+
+   mkdir gmx_md_example
+   cd gmx_md_example
+   cp ../tests/data/complex.* .
+   bss_production_gromacs --inp complex.prm7 complex.rst7 --runtime 0.1 --save_name gmx_md_out --dump_to .
+
+You should now have the final coordinate file, ``gmx_md_out.rst7``, a copy of the input topology file ``gmx_md_out.prm7``, and a sub-directory containing all of the
+intermediate files. Note that despite running through GROMACS, we were able to pass in AMBER files as input. This is because BioSimSpace automatically converts
+between file formats (using Sire under the hood).
+

_build/_sources/tutorial_cli_system_preparation.rst.txt

@@ -0,0 +1,53 @@
+System Preparation
+==================
+
+Often, we have structure files for a protein and / or ligand and we would like to parameterise, solvate, minimise, heat, and equilibrate them to obtain systems
+suitable for production molecular dynamics simulations or free energy calculations. While individual nodes are provided for all of these steps, 
+`maize-biosimspace` also provides CLIs for two complete system preparation workflows: ``bss_system_prep_free``, which is designed to prepare a ligand in a box
+of water (but can also be used for an apo protein) and ``bss_system_prep_bound``, which is designed to set up protein-ligand complexes. 
+
+Here, we'll prepare the complex of T4 lysozyme L99A bound to benzene, a very common test system for absolute binding free energy calculations. First, we'll copy 
+over the required input:
+
+.. code-block:: bash
+
+   mkdir sysprep_bound_example
+   cd sysprep_bound_example
+   cp ../tests/data/benzene.sdf .
+   cp ../tests/data/t4l.pdb .
+
+.. tip::
+
+   This pdb has been sanitised and will work with BioSimSpace first time, but often pdbs will require some tweaking before they are accepted by ``tleap`` (which 
+   BioSimSpace uses behind the scenes). The recommended workflow is
+
+   * Clean your unsanitised pdb using pdb4amber, e.g. ``pdb4amber -i protein.pdb -o protein_sanitised.pdb``
+   * Attempt to run the workflow below
+   * If the workflow raises an error, attempt parameterisation directly with ``tleap`` to get more detailed error messages. E.g., type ``tleap``, then
+
+   .. code-block:: bash
+
+      source leaprc.protein.ff14SB
+      source leaprc.water.tip3p
+      # Loading an unsanitised pdb will likely raise an error
+      prot = loadpdb protein_sanitised.pdb
+      saveamberparm prot protein.parm7 protein.rst7
+      savepdb prot protein_fully_sanitised.pdb
+
+   * If the above fails, this is often due to residue/ atom names which do not match the templates. Read the errors to find out which residues / atoms are causing the issues, then check the expected names in library which was loaded after typing ``source leaprc.protein.ff14SB`` e.g. ``cat $AMBERHOME/dat/leap/lib/amino12.lib``.  Rename the offending atoms/ residues and repeat the above step.
+
+   BioSimSpace is very fussy about parameterisation and will fail if tleap raises any warnings. To get round this, run the tleap script above and use the
+   ``protein_full_sanitised.pdb`` file as your input, which will not raise any errors.
+
+To run system preparation for our protein-ligand complex, we'll use the ``bss_system_prep_bound`` CLI, saving the output system to "t4l_benzene_complex_equilibrated"
+and using the gaff2 ff14SB force fields. There are a large number of other parameters which can be modified (see ``bss_system_prep_bound -``) but we'll run the 
+defaults for now.
+
+.. note::
+
+   Make sure that you have access to a GPU locally, or have configured `Maize` to submit to a queue with gpu access (see :doc:`configuration`)
+
+.. code-block:: bash
+
+   bss_system_prep_bound --inp benzene.sdf --protein_pdb t4l.pdb --ligand_force_field gaff2 --protein_force_field ff14SB --save_name t4l_benezene_complex_equilibrated
+

_build/_sources/tutorial_python_production.rst.txt

@@ -0,0 +1,63 @@
+Creating a Workflow with Production MD
+=======================================
+
+Here, we'll look at a basic example of a custom workflow which 
+uses ``pmemd.cuda`` to run some production MD. In reality, you 
+would want to add some extra steps before or afterwards:
+
+.. code-block:: python
+
+    """Run production Molecular Dynamics using PMEMD.CUDA through BioSimSpace."""
+
+    from pathlib import Path
+
+    from maize.core.workflow import Workflow
+    from maize.steps.exs.biosimspace import ProductionPmemdCuda
+    from maize.steps.io import LoadData, Return
+    from maize.utilities.execution import JobResourceConfig
+
+    # Build the graph
+    flow = Workflow(name="Prod_BSS_AMBER_Test", cleanup_temp=False, level="debug")
+
+    # Add the nodes
+    load_sys = flow.add(LoadData[list[Path]])
+    prod_pmemd = flow.add(
+        ProductionPmemdCuda,
+        name="Production_Amber",
+        parameters={
+            "runtime": 1.0, # ns
+        },
+    )
+    retu = flow.add(Return[list[Path]])
+
+    # Set parameters
+    load_sys.data.set(
+        [
+            Path(
+                "< path to complex.prm7>" # CHANGEME
+            ),
+            Path(
+                "< path to complex.rst7>" # CHANGEME
+            ),
+        ]
+    )
+
+    # Connect the nodes
+    flow.connect(load_sys.out, prod_pmemd.inp)
+    flow.connect(prod_pmemd.out, retu.inp)
+
+    # Check and run!
+    flow.check()
+    flow.visualize()
+    flow.execute()
+
+    mols = retu.get()
+
+    # Load a BioSimSpace system from the returned paths
+    import BioSimSpace as BSS
+
+    sys = BSS.IO.readMolecules([str(mols[0]), str(mols[1])])
+    print(40 * "#")
+    print(sys)
+    # In reality, you would do something here...
+