https://github.com/eltrompetero/coniii
Convenient Interface to Inverse Ising (ConIII)
https://github.com/eltrompetero/coniii
inference inverse-ising ising maxent python spin-glass statistics
Last synced: 12 days ago
JSON representation
Convenient Interface to Inverse Ising (ConIII)
- Host: GitHub
- URL: https://github.com/eltrompetero/coniii
- Owner: eltrompetero
- License: mit
- Created: 2018-10-22T19:14:03.000Z (over 7 years ago)
- Default Branch: py3
- Last Pushed: 2026-06-02T22:10:02.000Z (13 days ago)
- Last Synced: 2026-06-02T23:14:07.911Z (13 days ago)
- Topics: inference, inverse-ising, ising, maxent, python, spin-glass, statistics
- Language: Python
- Homepage:
- Size: 15.1 MB
- Stars: 21
- Watchers: 2
- Forks: 11
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
[](https://github.com/eltrompetero/coniii/actions/workflows/test.yml) [](https://pypi.python.org/pypi/coniii/) [](https://pypi.python.org/pypi/coniii/)
# 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](https://coniii.readthedocs.io/en/latest/ "Documentation").
## 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.
```bash
$ 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.
```bash
$ 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):
```bash
$ 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](https://github.com/eltrompetero/coniii/blob/py3/ipynb/usage_guide.ipynb) 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
```bash
$ 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
```bash
$ 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
```bash
$ pytest -q
```
The package directory can be found by running inside python
```python
>>> import coniii
>>> coniii.__path__
```
You may also need to install pytest.
```bash
$ conda install -c conda-forge pytest
```
### Updating
When updating, please read the [RELEASE_NOTES](https://github.com/eltrompetero/coniii/blob/py3/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.