DEVREADME

# ====================================================================================== #
# Developer / maintainer notes.
# Author: Eddie Lee, edlee@santafe.edu
# ====================================================================================== #

Branches
--------
- Development happens on `dev`. Releases are merged into `py3`.
- CI (.github/workflows/test.yml) runs pytest on Python 3.9-3.13 across Linux, macOS, and Windows
  for pushes and PRs to both branches. It can also be run manually on any branch from the Actions tab (workflow_dispatch).


Project layout
--------------
- Package metadata lives in pyproject.toml (PEP 517/518). It is the single source of
  truth; the version is read dynamically from coniii/version.py.
- setup.py only declares the optional Boost.Python C++ extension
  (coniii.samplers_ext). If Boost is not found at build time the extension is skipped
  and the pure-Python samplers are used at runtime.


Building and publishing to PyPI
-------------------------------
- Build sdist + wheel:
    python -m build
  (or run ./pypi_compile.sh, which also renames the Linux wheel to manylinux1 and,
  with --all, refreshes the bundled usage_guide.ipynb and builds the docs).
- Test upload:
    twine upload --repository testpypi dist/*
  Install from the test server from OUTSIDE the project directory (otherwise pip thinks
  the project is already installed because it is on your path):
    pip install --index-url https://test.pypi.org/simple/ coniii
- Release upload:
    twine upload --repository pypi dist/*
- Credentials are read from ~/.pypirc.


Documentation (Read the Docs)
-----------------------------
- Docs are hosted at https://coniii.readthedocs.io and rebuilt automatically by Read
  the Docs on each push (configured via .readthedocs.yaml).
- To build the HTML locally for a preview:
    sphinx-build ./docs/ ./docs/_build/html
- There is no longer any manual rsync/publish step; do not commit docs/_build/.


Notes on the Boost extension
----------------------------
- The Boost python and numpy libraries must be on both LIBRARY_PATH and
  LD_LIBRARY_PATH: the former is used by gcc at compile time, the latter by the program
  at run time.
- For compilation they must also be on CPLUS_INCLUDE_PATH. Pointing at the conda
  environment's include directory usually works; setting the env var explicitly is an
  alternative.
- Header paths (e.g. "boost/python/numpy.hpp") must be on the include path. setup.py
  probes CONDA_PREFIX/include/boost and the system include dirs; extend include_dirs in
  setup.py if your environment is unusual.
- An `ld` error means a dynamic-library linking problem. Copy the g++ call and add `-v`
  to see the detailed link step.


Regenerating Ising equation files
---------------------------------
- coniii/ising_eqn/ holds machine-generated equation modules. Regenerate one with:
    python -m coniii.enumerate N [sym] [order] [-hp=true]
  or regenerate the standard set with coniii/write_ising_files.sh.