Merge pull request #21 from andrewtarzia/scram_dev

Bring in topology scrambler module - still a WIP.

README.rst

@@ -0,0 +1,108 @@
+:maintainers:
+  `andrewtarzia <https://github.com/andrewtarzia/>`_
+:documentation: https://cgexplore.readthedocs.io/en/latest/
+
+.. figure:: docs/source/_static/logo.png
+
+
+Overview
+========
+
+:mod:`cgexplore` or ``cgx`` is a general toolkit built on
+`stk <https://stk.readthedocs.io/en/stable/>`_ for constructing,
+optimising and exploring molecular coarse-grained models.
+
+.. important::
+
+  **Warning**: This package is still very much underdevelopment and many changes
+  are expected.
+
+Installation
+============
+
+:mod:`cgexplore` can be installed with pip:
+
+.. code-block:: bash
+
+  pip install cgexplore
+
+With dependancies `openmm <https://openmm.org/>`_ and `openmmtools <https://openmmtools.readthedocs.io/en/stable/gettingstarted.html>`_:
+
+.. code-block:: bash
+
+  mamba install openmm openmmtools
+
+
+Then, update directory structure in `env_set.py` if using example code.
+
+
+The library implements some analysis that uses `Shape 2.1`. Follow the
+instructions to download and installed at
+`Shape <https://www.iqtc.ub.edu/uncategorised/program-for-the-stereochemical-analysis-of-molecular-fragments-by-means-of-continous-shape-measures-and-associated-tools/>`_
+
+
+Developer Setup
+---------------
+
+To develop with :mod:`cgexplore`, you can clone the repo and use
+`just <https://github.com/casey/just>`_ to setup the dev environment:
+
+.. code-block:: bash
+
+  just dev
+
+
+Usage
+=====
+
+**To reproduce data in DOI:
+`10.1039/D3SC03991A <https://doi.org/10.1039/D3SC03991A>`_**:
+Download the source code from `first_paper_example - presubmission`
+release from ``Releases``.I do not guarantee that running the example code
+on the current version will work. However, with each pull request a test is run
+as a GitHub Action connected to this
+`repository <https://github.com/andrewtarzia/cg_model_test>`_.
+This ensures that the results obtained for a subset of the original data set
+do not change with changes to this library. Additionally, the naming
+convention has changed and force field xml files should provide the
+appropriate information for mapping angles to models.
+
+
+* The directory `cgexplore` contains the actual source code for the package.
+* The directory `first_paper_example` contains the code for `10.1039/D3SC03991A <https://doi.org/10.1039/D3SC03991A>`_.
+  * `generate_XX.py` generates cage structures for different topology sets
+  * `env_set.py` sets a specific environment for file outputs
+  * `plot_XX.py` produces images and figures, and performs analysis
+
+.. important::
+  **Warning**: If you have a CUDA-capable GPU and attempt to use CUDA in the
+  first example, you may get `NaN` errors due to the torsion restriction for
+  angles at 180 degrees, which cause problematic forces. This will be handled
+  in future versions of the code. And logically, I would suggest removing the
+  torsion restriction for those angles. The `platform` can be handled through
+  this argument in `build_building_blocks` and `build_populations`, which I
+  currently set to `None`, meaning `OpenMM` will decide for itself.
+
+
+How To Cite
+===========
+
+If you use ``stk`` please cite
+
+  https://github.com/andrewtarzia/CGExplore
+
+and
+
+  https://pubs.rsc.org/en/content/articlelanding/2023/sc/d3sc03991a
+
+Publications using CGExplore
+============================
+
+* Using stk for constructing larger numbers of coarse-grained models: `Systematic exploration of accessible topologies of cage molecules via minimalistic models`__
+
+
+Acknowledgements
+================
+
+Funded by the European Union - Next Generation EU, Mission 4 Component 1
+CUP E13C22002930006 and the ERC under projects DYNAPOL.

docs/source/_autosummary/cgexplore.atomistic.Crest.rst

@@ -0,0 +1,26 @@
+cgexplore.atomistic.Crest
+=========================
+
+.. currentmodule:: cgexplore.atomistic
+
+.. autoclass:: Crest
+   :members:
+   :inherited-members:
+   :undoc-members:
+   :show-inheritance:
+
+
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+      :nosignatures:
+
+      ~Crest.optimize
+
+
+
+
+
+

docs/source/_autosummary/cgexplore.atomistic.cgx_optimisation_sequence.rst

@@ -0,0 +1,6 @@
+cgexplore.atomistic.cgx\_optimisation\_sequence
+===============================================
+
+.. currentmodule:: cgexplore.atomistic
+
+.. autofunction:: cgx_optimisation_sequence

docs/source/_autosummary/cgexplore.atomistic.extract_ensemble.rst

@@ -0,0 +1,6 @@
+cgexplore.atomistic.extract\_ensemble
+=====================================
+
+.. currentmodule:: cgexplore.atomistic
+
+.. autofunction:: extract_ensemble

docs/source/_autosummary/cgexplore.atomistic.rst

@@ -0,0 +1,43 @@
+cgexplore.atomistic
+===================
+
+.. automodule:: cgexplore.atomistic
+
+
+
+
+
+
+
+   .. rubric:: Classes
+
+   .. autosummary::
+      :toctree:
+      :template: class.rst
+      :nosignatures:
+
+      Crest
+
+
+
+
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+
+      cgx_optimisation_sequence
+      extract_ensemble
+      run_conformer_analysis
+
+
+
+
+
+
+
+
+

docs/source/_autosummary/cgexplore.atomistic.run_conformer_analysis.rst

@@ -0,0 +1,6 @@
+cgexplore.atomistic.run\_conformer\_analysis
+============================================
+
+.. currentmodule:: cgexplore.atomistic
+
+.. autofunction:: run_conformer_analysis

docs/source/_autosummary/cgexplore.forcefields.custom_lennard_jones_force.rst

@@ -0,0 +1,6 @@
+cgexplore.forcefields.custom\_lennard\_jones\_force
+===================================================
+
+.. currentmodule:: cgexplore.forcefields
+
+.. autofunction:: custom_lennard_jones_force

docs/source/_autosummary/cgexplore.forcefields.rst

@@ -38,6 +38,7 @@ cgexplore.forcefields
 
       cosine_periodic_angle_force
       custom_excluded_volume_force
+      custom_lennard_jones_force
       get_martini_mass_by_type
 
 

docs/source/_autosummary/cgexplore.rst

@@ -30,9 +30,11 @@
    :recursive:
 
    analysis
+   atomistic
    forcefields
    molecular
    optimisation
+   scram
    systems_optimisation
    terms
    topologies

docs/source/_autosummary/cgexplore.scram.Constructed.rst

@@ -0,0 +1,34 @@
+cgexplore.scram.Constructed
+===========================
+
+.. currentmodule:: cgexplore.scram
+
+.. autoclass:: Constructed
+   :members:
+   :inherited-members:
+   :undoc-members:
+   :show-inheritance:
+
+
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+      :nosignatures:
+
+
+
+
+
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~Constructed.mash_idx
+      ~Constructed.constructed_molecule
+      ~Constructed.idx
+      ~Constructed.topology_code
+
+

docs/source/_autosummary/cgexplore.scram.HomolepticTopologyIterator.rst

@@ -0,0 +1,25 @@
+cgexplore.scram.HomolepticTopologyIterator
+==========================================
+
+.. currentmodule:: cgexplore.scram
+
+.. autoclass:: HomolepticTopologyIterator
+   :members:
+   :inherited-members:
+   :undoc-members:
+   :show-inheritance:
+
+
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+      :nosignatures:
+
+
+
+
+
+
+