|
1 | | -Python 3 package for solving the inverse maximum entropy problem with a focus on |
2 | | -the pairwise maximum entropy model, also known as the inverse Ising problem. |
| 1 | +[](https://pypi.python.org/pypi/coniii/) [](https://pypi.python.org/pypi/coniii/) |
3 | 2 |
|
4 | | -See GitHub page for overview on package use and extensions. Directions for |
5 | | -massive speed up of Metropolis sampling with C++ are also available there. |
| 3 | +# Convenient Interface to Inverse Ising |
6 | 4 |
|
7 | | -Examples are included in the Jupyter notebook "usage_guide.ipynb" and the Python |
8 | | -script "usage_guide.py" (see GitHub). An overview for version 1 is also |
9 | | -published in the |
10 | | -[paper](https://github.com/eltrompetero/coniii/blob/py3/guide/guide.pdf). |
| 5 | +ConIII is a Python package for solving maximum entropy problems with a focus on the |
| 6 | +pairwise maximum entropy model, also known as the inverse Ising problem. Support for |
| 7 | +Python 3.8.3 and higher. |
11 | 8 |
|
12 | | -Authors: Edward D. Lee, Bryan C. Daniels |
| 9 | +If you use ConIII for your research, please consider citing the following: |
| 10 | +> Lee, E.D. and Daniels, B.C., 2019. Convenient Interface to Inverse Ising (ConIII): A |
| 11 | +> Python 3 Package for Solving Ising-Type Maximum Entropy Models. Journal of Open Research |
| 12 | +> Software, 7(1), p.3. DOI: http://doi.org/10.5334/jors.217. |
| 13 | + |
| 14 | +The paper also contains an overview of the modules. For code documentation, see |
| 15 | +[here](https://eddielee.co/coniii/index.html "Documentation"). |
| 16 | + |
| 17 | +## Installation |
| 18 | + |
| 19 | +This package is available on PyPI. It can be installed by first installing the needed |
| 20 | +Boost C++ libraries and using pip. |
| 21 | +```bash |
| 22 | +$ conda install -c conda-forge boost==1.74 |
| 23 | +$ pip install coniii |
| 24 | +``` |
| 25 | +If you have trouble using `pip`, then you can always build this package from |
| 26 | +source. The following code will down download the latest release from GitHub and install |
| 27 | +the package. Make sure that you are running Python 3.8.3 or higher and have boost v1.74.0 |
| 28 | +installed. |
| 29 | +```bash |
| 30 | +$ git clone https://github.com/eltrompetero/coniii.git |
| 31 | +$ cd coniii |
| 32 | +$ ./pypi_compile.sh |
| 33 | +$ pip install dist/*.whl |
| 34 | +``` |
| 35 | +(Note: Using setuptools in the usual way of `python |
| 36 | +setup.py install` will not work because eggs are incompatible with cached jit functions |
| 37 | +generated using numba.) |
| 38 | + |
| 39 | +#### Setting up exact solution for systems *N > 9* |
| 40 | +If you would like to use the `Enumerate` solver for system sizes greater than 9 spins, you |
| 41 | +must run enumerate.py to write those files yourself. This can be run from the install |
| 42 | +directory. If you do not know where the installation directory is, you can find it by |
| 43 | +starting a Python terminal and running |
| 44 | +```python |
| 45 | +>>> import coniii |
| 46 | +>>> coniii.__path__ |
| 47 | +``` |
| 48 | + |
| 49 | +Once inside the install directory, you can run in your bash shell |
| 50 | +```bash |
| 51 | +$ python enumerate.py [N] |
| 52 | +``` |
| 53 | + |
| 54 | +where `[N]` should be replaced by the size of the system. This will write the equations |
| 55 | +for the Ising model in the {0,1} basis. On the other hand, |
| 56 | + |
| 57 | +```bash |
| 58 | +$ python enumerate.py [N] 1 |
| 59 | +``` |
| 60 | + |
| 61 | +specifies that the system should be written for the {-1,1} basis. Note that the package |
| 62 | +uses the {-1,1} basis by default. For more details, see the `__main__` block at the end of |
| 63 | +the file enumerate.py. |
| 64 | + |
| 65 | +## Quick guide (with Jupyter notebook) |
| 66 | + |
| 67 | +A [Jupyter |
| 68 | +notebook](https://github.com/eltrompetero/coniii/blob/py3/ipynb/usage_guide.ipynb) with a |
| 69 | +brief introduction and examples for how to use ConIII is available. An HTML version is |
| 70 | +[here](https://github.com/eltrompetero/coniii/blob/py3/ipynb/usage_guide.html). The |
| 71 | +notebook is installed into your package directory if you used pip. |
| 72 | + |
| 73 | +To use the notebook, install jupyter. |
| 74 | +```bash |
| 75 | +$ pip install jupyter |
| 76 | +``` |
| 77 | +or if you are using the Conda package manager |
| 78 | +```bash |
| 79 | +$ conda install jupyter |
| 80 | +``` |
| 81 | + |
| 82 | +Then, first copy the notebook file "usage_guide.ipynb" into a directory outside the |
| 83 | +"coniii" directory. Change to this directory and run |
| 84 | +```bash |
| 85 | +$ jupyter notebook |
| 86 | +``` |
| 87 | + |
| 88 | +This should open the notebook in your default web browser. |
| 89 | + |
| 90 | +## Quick guide (console) |
| 91 | + |
| 92 | +First, install iPython for a console-based interpreter and start it. |
| 93 | +```bash |
| 94 | +$ pip install ipython |
| 95 | +``` |
| 96 | +or if you are using the Conda package manager |
| 97 | +```bash |
| 98 | +$ conda install ipython |
| 99 | +``` |
| 100 | + |
| 101 | +Then, first copy the notebook file |
| 102 | +["usage_guide.py"](https://github.com/eltrompetero/coniii/blob/py3/ipynb/usage_guide.py) |
| 103 | +into a directory outside the "coniii" directory. Change to this directory and run |
| 104 | +```bash |
| 105 | +$ ipython |
| 106 | +``` |
| 107 | + |
| 108 | +Once inside the iPython interpreter, run |
| 109 | +```python |
| 110 | +>>> %run usage_guide.py |
| 111 | +``` |
| 112 | +This will run all the examples sequentially, so you may want to comment out unwanted lines. |
| 113 | + |
| 114 | +## Troubleshooting |
| 115 | + |
| 116 | +This package is only maintained for Python 3 and has only been tested for Python |
| 117 | +3.8.3. Check which version of Python you are running in your terminal with |
| 118 | +```bash |
| 119 | +$ python --version |
| 120 | +``` |
| 121 | + |
| 122 | +ConIII has been tested on the following systems |
| 123 | +* Ubuntu 18.04 |
| 124 | +* Ubuntu 20.04.1 |
| 125 | + |
| 126 | +Trouble compiling the Boost extension manually? Check if your Boost library is |
| 127 | +included in your path. If it is not, then you can add an include directory entry |
| 128 | +into the `EXTRA_COMPILE_ARGS` variable in "setup.py" before compiling. |
| 129 | + |
| 130 | + |
| 131 | +### Support |
| 132 | + |
| 133 | +Please file an issue on the GitHub if you have any problems or feature requests. Provide a |
| 134 | +stack trace or other information that would be helpful in debugging. For example, OS, |
| 135 | +system configuration details, and the results of unit tests. Unit tests can be run by |
| 136 | +navigating to the package directory and running |
| 137 | + |
| 138 | +```bash |
| 139 | +$ pytest -q |
| 140 | +``` |
| 141 | + |
| 142 | +The package directory can be found by running inside python |
| 143 | +```python |
| 144 | +>>> import coniii |
| 145 | +>>> coniii.__path__ |
| 146 | +``` |
| 147 | + |
| 148 | +You may also need to install pytest. |
| 149 | +```bash |
| 150 | +$ pip install pytest |
| 151 | +``` |
| 152 | + |
| 153 | +### Updating |
| 154 | + |
| 155 | +When updating, please read the [RELEASE_NOTES](https://github.com/eltrompetero/coniii/blob/py3/RELEASE_NOTES). There may |
| 156 | +be modifications to the interface including parameter names as we make future versions |
| 157 | +more user friendly. |
| 158 | + |
| 159 | +[Documentation](https://eddielee.co/coniii/index.html "Documentation"). |
0 commit comments