Convenient Interface to Inverse Ising

ConIII is a Python package for solving maximum entropy problems with a focus on the pairwise maximum entropy model, also known as the inverse Ising problem.

If you use ConIII for your research, please consider citing the following:

Lee, E.D. and Daniels, B.C., 2019. Convenient Interface to Inverse Ising (ConIII): A Python 3 Package for Solving Ising-Type Maximum Entropy Models. Journal of Open Research Software, 7(1), p.3. DOI: http://doi.org/10.5334/jors.217.

The paper also contains an overview of the modules. For code documentation, see coniii.readthedocs.io.

Package layout

Area	Status	What's there
coniii.solvers	stable	Inverse-Ising solvers: Enumerate, SparseEnumerate, MPF, MCH, Pseudo, ClusterExpansion, RegularizedMeanField.
coniii.samplers	stable	Monte Carlo samplers: Metropolis, WolffIsing, ParallelTempering, Potts3, and the sample_ising helper.
coniii.models	stable	Maxent model classes: Ising, Triplet, Potts3.
coniii.utils	stable	Indexing, correlation, parameter-conversion, and helper-function utilities.
coniii.enumerate, coniii.enumerate_potts, coniii.ising_eqn	stable	Exact enumeration and the generated equation files it produces.
coniii.experimental	work in progress	Unvalidated samplers (SWIsing, HamiltonianMC, Heisenberg3DSampler) and an entropy stub. Not imported by import coniii; import explicitly.
coniii.legacy	deprecated	mean_field_ising (still used internally by ClusterExpansion/RegularizedMeanField) and pseudo_inverse_ising. Direct imports warn.

The top-level names available via from coniii import * are listed in coniii.__all__.

Installation

To set up an Anaconda environment called "test" and install from pip, run the following code. The openblas package is only recommended for AMD users.

$ conda create -n test -c conda-forge python=3.10 numpy scipy numba cython jupyter ipython multiprocess boost==1.74 matplotlib mpmath blas=*=openblas
$ pip install coniii

If you have trouble using pip, you can build from source. Make sure you are running Python 3.10 and have boost v1.74.0 installed.

$ git clone https://github.com/eltrompetero/coniii.git
$ cd coniii
$ pip install .

The build probes for Boost and compiles the optional C++ samplers extension if it is found; without Boost it falls back to the (slower) pure-Python samplers. To build distributable wheels instead, run python -m build (or the convenience wrapper ./pypi_compile.sh).

Setting up exact solution for systems N > 9

Enumerate ships with precomputed equation files up to N = 9. For larger systems, generate the file yourself by running the enumerate module (works from any directory):

$ python -m coniii.enumerate [N] 1

where [N] is the system size. The trailing 1 selects the {-1,1} basis (the package default); omit it for the {0,1} basis. See the __main__ block at the end of enumerate.py for more options.

Quick guide with Jupyter notebook

A Jupyter notebook with a brief introduction and examples for how to use ConIII is available. The notebook is also installed into your package directory if you used pip.

To use the notebook, install jupyter such as by following the setup instructions above. Then, copy the notebook file "usage_guide.ipynb" into a directory outside the "coniii" directory. Change to this directory and run

$ jupyter notebook

This should open the notebook in your default web browser.

Troubleshooting

This package is maintained for Python 3 and has been tested on Python 3.10. Check which version you are running with

$ python --version

ConIII has been tested on the following systems

• Ubuntu 20.04.5

Trouble compiling the Boost extension? Check that your Boost library is on the include path. If it is not, add the include directory to include_dirs in the _detect_boost() function in "setup.py" before compiling.

Support

Please file an issue on the GitHub if you have any problems or feature requests. Provide a stack trace or other information that would be helpful in debugging. For example, OS, system configuration details, and the results of unit tests. Unit tests can be run by navigating to the package directory and running

$ pytest -q

The package directory can be found by running inside python

>>> import coniii
>>> coniii.__path__

You may also need to install pytest.

$ conda install -c conda-forge pytest

Updating

When updating, please read the RELEASE_NOTES. There may be modifications to the interface including parameter names as we make future versions more user friendly. Note: v4.0.0 contains breaking changes — see the RELEASE_NOTES before upgrading.