RELEASE_NOTES

Log for major changes in releases


v4.0.2 (Released 2026/06)
----------------------------------------------------
- solvers.Pseudo now computes the analytic Hessian and solves with a
  Newton method (Newton-CG) by default, converging in fewer iterations
  (per Aurell & Ekeberg 2012). The optimizer is overridable via
  solver_kwargs={'method': ...}. (#21)
- Fixed a sign inconsistency in the per-spin (Ising) pseudolikelihood
  objective: the L1 penalty was added to the objective value but
  subtracted in the gradient, so the optimizer converged to a poor
  solution. Value and gradient now agree, substantially improving the
  default Pseudo solution.


v4.0.1 (Released 2026/06)
----------------------------------------------------
Bug fixes:
- Integer-typed multipliers are now coerced to float in the model and
  sampler classes. Previously an int multiplier vector made calc_e do
  integer arithmetic, giving wrong energies and badly wrong samples
  (e.g. from MCH). (#34)
- solvers.RegularizedMeanField no longer crashes on (nearly)
  degenerate data (pairwise correlations at +/-1). The objective is
  guarded against non-finite values, the default search is bounded
  (avoiding the fragile bracketing step), and a clear error is raised
  if no finite solution exists. (#16)
- Added a regression test confirming MCH is reproducible with a fixed
  random number generator. (#28)


v4.0.0 (Released 2026/06) — BREAKS COMPATIBILITY, READ NOTES
----------------------------------------------------
- Cleanup release. See RELEASE_NOTES for details.

Removed (breaking)
~~~~~~~~~~~~~~~~~~
- `utils.convert_corr`: removed the `convertTo` keyword. It was
  renamed to `convert_to` in v1.1.2 (Dec 2018) and warned for 6+
  years. Migration: rename the keyword.
- `solvers.Pseudo`: removed the deprecated implementation methods
  `_solve_ising_deprecated`, `cond_log_likelihood`, `cond_jac`,
  `cond_hess`, `pair_cooc_mat`, `pseudo_log_likelihood`. These were
  superseded by the standard algorithm introduced in v2.1.0
  (Nov 2019).
- `enumerate._write_matlab`: removed. Dead since it was added
  (no in-tree callers; the docstring already said "DEPRECATED:
  code here for future referencing").
- `from coniii import *` no longer re-exports `np`, `jit`, `njit`,
  `warn`, `ALPHNUM`, `NUMERALS`, `combinations`, `binom`,
  `multinomial`, `squareform`. Import them directly from their
  source modules.

Fixed
~~~~~
- `solvers.MPF`: passing a custom `adj` (or `calc_de`) to the
  constructor previously left `self.adj`/`self.calc_de` unset and
  raised `AttributeError` during `solve()`. The default path was
  unaffected. Both attributes are now always assigned.

Moved
~~~~~
- `coniii.mean_field_ising` → `coniii.legacy.mean_field_ising`.
  Direct imports emit a `DeprecationWarning`. Used internally by
  `ClusterExpansion` and `RegularizedMeanField` (silently).
- `coniii.pseudo_inverse_ising` → `coniii.legacy.pseudo_inverse_ising`.
  Direct imports emit a `DeprecationWarning`. Not wrapped by any
  solver class.
- `samplers.SWIsing`, `samplers.HamiltonianMC`,
  `samplers.Heisenberg3DSampler` → `coniii.experimental.samplers`.
  These had been raising `NotImplementedError` on construction and
  are kept out of the top-level namespace until validated.

Other
~~~~~
- Build modernized: real `pyproject.toml` (PEP 517/518), slimmer
  `setup.py` that only declares the optional Boost C++ extension.
  Boost is now optional in CI and on systems without conda.
- GitHub Actions CI runs pytest on push to dev/py3.
- Each public module now declares an explicit `__all__`. The names
  available via `from coniii import *` are now a curated 39 instead
  of 55 wildcard re-exports.
- Internal: `calc_e` numba signature was relaxed from
  `int64[:,:]` to accept any integer width; this unblocks MCH on
  systems where the Boost C++ extension is not compiled.
- Internal: dozens of `scipy.X` aliases that scipy 2.0 will remove
  were replaced with their `numpy.X` equivalents.
- `coniii.utils` is now a package split into focused submodules
  (`_indexing`, `_correlations`, `_params`, `_graph`). The public
  API is unchanged.
- Every module now has a proper module-level docstring.
- Docs: README has a new "Package layout" table flagging
  stable/experimental/legacy modules; documentation links now point
  to https://coniii.readthedocs.io. The stale `pypi_description`
  file was removed (README is the PyPI long description).
- Docs build configured for Read the Docs: added `.readthedocs.yaml`
  and a `[docs]` install extra; Sphinx now uses `napoleon` (for the
  numpy-style docstrings), `viewcode`, and the Read the Docs theme;
  the API reference toctree was rewritten to match the current
  module layout.
- Includes the previously-unreleased v3.0.2 work: setup-script
  improvements and Python 3.10 compatibility.

v3.0.1 (Released 2022/10)
----------------------------------------------------
- Bug fix in setup script.

v3.0.0 (Released 2022/06)
----------------------------------------------------
- Conditional (fixed spin) Metropolis sampling now in C++).
- Standardized method names for generating samples and data member names for
  sample to "generate_sample" and the singular "sample".
- Better handling of conda include paths and Python version in setup.

v2.4.4 (Released 2021/10)
----------------------------------------------------
- Updated conditional Metropolis sampling.

v2.4.3 (Released 2021/05)
----------------------------------------------------
- Maintenance release to quash multiple bugs including one introduced in last
  release. 

v2.4.2 (Released 2021/04)
----------------------------------------------------
- Fixed instantiation bug in model.Ising (thanks to saynbabul for pointing this
  out).

v2.4.1 (Released 2021/01)
----------------------------------------------------
- Fixed new bugs in installation scripts.

v2.4.0 (Released 2021/01)
----------------------------------------------------
- Update for Python 3.8.3 and Boost 1.74.0.
- New SparseEnumerate class for handling sparsely constrained system.

v2.3.1 (Released 2020/10)
----------------------------------------------------
- Automated linking of Boost C++ module using conda-forge.

v2.3.0 (Released 2020/05)
----------------------------------------------------
- Sped up Metropolis sampling using Boost C++ extension. Up to 1000x speedup
  achievable compared to Python version. This must be compiled separately and is
  not yet available through a PyPI installation.
- Added variation of 3-state Potts model.

v2.2.1 (Released 2019/12/2)
----------------------------------------------------
- Random number generator use update in RegularizedMeanField.

v2.1.1 (Released 2019/11/29) 
----------------------------------------------------
- Added convenient multiplier transformation functions utils.vec2mat and
  utils.mat2vec.
- Output from ClusterExpansion.solve is of different order when
  full_output=True. Now, entropy estimate comes second instead of first to
  maintain consistency for when full_output=False.

v2.1.0 (Released 2019/11/28) 
----------------------------------------------------
- Fixed bug in Pseudo. It was using a non-standard algorithm for solving the
  Ising model.  Find more details in Issue #8
  (https://github.com/eltrompetero/coniii/issues/8).

v2.0.0 (Released 2019/11/28) VERSION RELEASE, BREAKS COMPATIBILITY, READ NOTES
----------------------------------------------------
- Simpler interface for using solvers with Ising model. No custom function
  definitions required. All are defined by default. Note that this will break
  compatibility with code relying on version 1. See usage_guide.ipynb for
  examples with new interface.
- New "models.py" module to wrap evaluation of and sampling from maxent models.
- Added a convenient Metropolis sampler call, samplers.sample_ising.

v1.2.2 (Released 2019/09/19)
----------------------------------------------------
- Minor maintenance.

v1.2.1 (Released 2019/05/31)
----------------------------------------------------
- Pseudo solver sped up and Ising-specific calculation removed.
- Bugs.

v1.2.0 (Released 2019/05/02)
----------------------------------------------------
- Bugs fixed in package setup for PyPI.

v1.1.9 (Released 2019/04/22)
----------------------------------------------------
- Added support for Potts models in new module enumerate_potts.py.
- Typos fixed in usage guide Jupyter notebook.
- Added Ising class in .ising module for wrapping some useful functions for use with the
  Ising model.

v1.1.8 (Released 2019/04/08)
----------------------------------------------------
- Bug fixes.

v1.1.7 (Released 2019/03/20)
----------------------------------------------------
- enumerate.py can now write files that handle arbitrary precision using mpmath. These are
  written to files using the prefix '_hp.py'.
- Interface bug fixes.
- Updated dependency requirements to later versions of numba and numpy and new dependency
  on mpmath.
- Some revisions to usage guide notebook.

v1.1.6 (Released 2019/03/12)
----------------------------------------------------
- Bug fixes.
- License date update.

v1.1.5 (Released 2019/02/24)
----------------------------------------------------
- Bug fixes.

v1.1.4 (Released 2019/01/06)
----------------------------------------------------
- Enumerate.solve() now uses scipy.optimize.root to find solution and is MUCH faster.

v1.1.3 (Released 2018/12/17)
----------------------------------------------------
- Update to Ising equation files in v1.1.0 to make them much smaller used Scipy's
  logsumexp function which is slow! With own light implementation, code is at least
  several times faster to evaluate.

v1.1.2 (Released 2018/12/16)
----------------------------------------------------
- Bug fix in type casting in Metropolis.generate_samples_parallel().
- convertTo kwarg for utils.convert_corr has been changed to convert_to to make it uniform
  with other functions.
- convert_to is no longer a keyword argument and is now a regular argument that must be
  specified as a string.

v1.1.0 (Released 2018/12/13)
----------------------------------------------------
- Bug fix in type casting in Metropolis.generate_samples_parallel().
- Now compatible with multiprocess v0.70.6
- Updated sampling method for Metropolis to be more efficient by running fewer systems for
  longer and taking iterative samples instead of starting with a completely new system for
  every sample (which takes longer to burn in and requires starting new processes). This
  is automated such that the number of samples is divided evenly amongst all running
  processes)..
- Added working version of ParallelTempering sampler.
- n_cpus and nCpus are now used to refer to number of allowed processes to spawn and got
  rid of cpu_count which can be confused in `multiprocess.cpu_count`.
- Improvements to enumerate.py: More compact Ising equation files and better precision by
  using scipy.special.logsumexp.
- Jupyter is no longer required for installation of ConIII by default.
- Ising functions (calc_e and functions that use it) assume that spins are now integer
  types. TypeError in jit is thrown if not. Updates to other functions for compatibility
  (e.g. utils.bin_states() return integer types).
- Removed use_numba switch for samplers.
- Removed FastMCIsing sampler.

v1.0.3 (Released 2018/11)
----------------------------------------------------
- First official release.