0.2.0 release (#15)

* Implemented SVD solution for MLE results

* Added standard errors for state free energies and transition rates

* `Multibind.effective_energy_difference` now returns an error estimate in addition to the
macroscopic free energy difference

* Added CHANGELOG and increased version to 0.2.0

Author: ianmkenney

.github/workflows/tests.yml

@@ -0,0 +1,38 @@
+name: Tests
+
+on:
+  push:
+    branches: [ master, develop ]
+  pull_request:
+    branches: [ master, develop ] 
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v2
+      with:
+        python-version: "3.10"
+    - name: Install poetry
+      run: |
+        python -m pip install --upgrade pip
+        pip install poetry
+    - name: Install multibind with poetry
+      run: |
+        poetry install
+    - name: Test with pytest
+      run: |
+        cd tests/
+        poetry run pytest -v --cov=multibind --cov-report=xml
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v2
+      with:
+        directory: .
+        fail_ci_if_error: true
+        files: coverage.xml
+        name: codecov-umbrella
+        verbose: true

.gitignore

@@ -6,3 +6,8 @@ __pycache__/
 .pytest_cache
 poetry.lock
 dist/
+.coverage
+coverage.xml
+docs/build/
+docs/_build/
+docs/generated/

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  install:
+    - method: pip
+      path: .

CHANGELOG

@@ -0,0 +1,5 @@
+2022-02-22    0.2.0
+ianmkenney
+
+Fully functional with tests and basic documentation.
+For details see the git log.

README.md

@@ -1,7 +1,7 @@
 # Multibind
 
 
-[![DOI](https://zenodo.org/badge/301552078.svg)](https://zenodo.org/badge/latestdoi/301552078)
+[![DOI](https://zenodo.org/badge/301552078.svg)](https://zenodo.org/badge/latestdoi/301552078) ![Tests](https://github.com/BecksteinLab/multibind/actions/workflows/tests.yml/badge.svg?branch=develop) [![codecov](https://codecov.io/gh/Becksteinlab/multibind/branch/develop/graph/badge.svg?token=7T3Z19P4W5)](https://codecov.io/gh/Becksteinlab/multibind) [![docs](https://readthedocs.org/projects/multibind/badge/?version=latest)](https://multibind.readthedocs.io/en/latest/?badge=latest)
 
 
 Thermodynamic cycles which are defined by a set of individually determined free energy differences are not guaranteed to be thermodynamically consistent.
@@ -12,14 +12,14 @@ Additionally, multibind supports cycles whose free energies are dependent on mul
 ## State definitions
 
 States are minimally defined by a name and should be added to a csv file.
-Macrostates can be added as additional columns with the name of the category being the column header.
+Macrostate classes can be added as additional columns with the name of the class being the column header.
 
 ```text
-name,bound
-1,unbound
-2,bound
-3,bound
-4,unbound
+name,n_protons,n_sodium
+1,0,0
+2,0,1
+3,1,0
+4,1,1
 ```
 
 ## Graph definition
@@ -30,12 +30,16 @@ These edges are the free energy differences between states and are characterized
 Multibind allows for three process type, which are specified under the ligand column:
 
 - "H+": proton binding which takes as its free energy value, the pKa.
-- "helm": undefined process which takes a free energy directly in kT.
 - general ligand: binding of a general ligand. The standard state free energy in kT. By defining the concentration to build the cycle, this free energy becomes concentration dependent.
+- "helm": undefined process which takes a free energy directly in kT.
 
-In defining the edges, always treat the free energies as going from state 1 to state 2.
+In defining the edges, always treat the free energies as going from state 1 to state 2 for that process.
+For 'H+', state 1 should be the deprotonated state and state 2 is the protonated state.
+For a general ligand, state 1 is the unbound state and state 2 is the bound state.
+Failure to do so will assign the negative of the desired free energy to that edge.
 
 ```text
+# graph.csv
 state1,state2,value,variance,ligand,standard_state
 1,2,-10,0.1,Na+,1
 2,3,5.697116,0.1,H+,1
@@ -45,16 +49,38 @@ state1,state2,value,variance,ligand,standard_state
 
 ## Example code
 
+The standard `Multibind` object is used to solve the graph at one point in concentration space.
+
 ```python
 import multibind as mb
 
+concentrations = {'Na': 0.150}
+
 c = mb.Multibind()
 c.read_graph("examples/input/4-state-diamond/graph.csv",comment="#")
 c.read_states("examples/input/4-state-diamond/states.csv")
+c.concentrations = concentrations
 c.build_cycle(pH=7)
-c.MLE() 
+c.MLE(svd=True) 
 # compute the effective energy difference between two macrostates
 # if you are unsure of the values to pass to the function, look
 # at either your state file or the contents of c.states
-c.effective_energy_difference("Nprotons",1,2)
+c.effective_energy_difference("N_protons",1,2)
+```
+
+The `MultibindScanner` can be used to scan across a bunch of concentrations.
+
+```python
+import multibind as mb
+
+state_file = 'examples/input/4-state-diamond/states.csv'
+graph_file = 'examples/input/4-state-diamond/graph.csv'
+
+scanner = mb.MultibindScanner(state_file, graph_file, comment_char='#')
+
+concentrations = {'H+': [7, 8, 9], 'Na+': [0.200, 0.150, 0.100]}
+# This will MLE calculations across 9 points in concentration space
+# the results will be in an xarray Dataset that can be accessed with
+# scanner.results
+scanner.run(concentrations, svd=True)
 ```

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api.rst

@@ -0,0 +1,8 @@
+API
+===
+
+.. autosummary::
+   :toctree: generated
+
+   multibind.multibind
+   multibind.nonequilibrium

docs/conf.py

@@ -0,0 +1,57 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../'))
+
+import multibind as mb
+
+# -- Project information -----------------------------------------------------
+
+project = 'multibind'
+copyright = '2022, Ian M. Kenney'
+author = 'Ian M. Kenney'
+
+# The full version, including alpha/beta/rc tags
+release = mb.__version__
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.autosummary',
+              ]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'default'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/derivations.pdf

@@ -0,0 +1,21 @@
+.. multibind documentation master file, created by
+   sphinx-quickstart on Tue Feb 15 11:00:52 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Multibind documentation
+=======================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   usage
+   api
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`