Move docs to gh-pages branch

.github/workflows/static.yml

@@ -4,7 +4,7 @@ name: Deploy static content to Pages
 on:
   # Runs on pushes targeting the default branch
   push:
-    branches: ["main"]
+    branches: ["gh-pages"]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:

_build/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: bcae3f18c5a5b744214b9588efab74fa
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_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

@@ -0,0 +1,79 @@
+.. maize-biosimspace documentation master file, created by
+   sphinx-quickstart on Wed Mar  8 17:24:58 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+maize-biosimspace
+=================
+*maize* is a graph-based workflow manager for computational chemistry pipelines. This repository contains a namespace package providing BioSimSpace extensions for *maize*. You can find the core maize documentation `here <https://molecularai.github.io/maize>`_.
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: Setup
+
+   installation
+   configuration
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+   :caption: Tutorials
+
+   cli_tutorials
+   python_tutorials
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: Reference
+
+   steps/index
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: Core
+
+   Steps <https://molecularai.github.io/maize/docs/steps>
+   Maize <https://molecularai.github.io/maize>
+
+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 ./
+
+Ensure that the required AMBER, GROMACS, and NAMD executables are available in your environment if you plan to use the relevant nodes.
+
+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.
+
+.. code-block:: bash
+
+   bss_parameterise -h
+
+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:
+
+.. 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 .
+
+This will run locally. To configure maize nodes to run through a scheduler such as slurm, see :doc:`configuration`.
+
+
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

_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/production-md.rst.txt

@@ -0,0 +1,61 @@
+Production MD
+==============
+
+An example of a production molecular dynamics workflow using BioSimSpace Maize nodes:
+
+.. 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...
+

_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/steps/biosimspace.rst.txt

@@ -0,0 +1,9 @@
+BioSimSpace
+==================
+
+.. automodule:: maize.steps.exs.biosimspace
+   :members:
+   :no-value:
+   :noindex:
+   :exclude-members: full_timer, run_timer, logger, target_dir, work_dir, run, build
+   :inherited-members: Node, Component

_build/_sources/steps/index.rst.txt

@@ -0,0 +1,11 @@
+.. _custom-steps:
+
+Steps
+=====
+This is the documentation of all contained steps.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Steps
+
+   biosimspace

_build/_sources/tutorial_cli_abfe.rst.txt

@@ -0,0 +1,49 @@
+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 0.01 ns of sampling per production window.
+Note that you currently need to provide the absolute path to your inputs:
+
+.. code-block:: bash
+
+   bss_abfe_multi_isomer --lig_sdfs_file <INSERT ABSOLUTE PATH TO benzene.sdf> \
+                         --protein_pdb_path <INSERT ABSOLUTE PATH to t4l.pdb> \
+                         --run_time_abfe 0.01 \
+                         --dump_to . \
+
+The results (see the log or ``results.json`` in the ``dump`` directory) should show
+a binding free energy of around -5 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.abfe_single_node import get_abfe_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).
+