COMPILING AND INSTALLING

CAMFR is a C++/Fortran library with a Python 3 interface built with
pybind11.

It has been tested on Ubuntu 26.04 with Python 3.14, NumPy 2.5, GCC and
gfortran 15, Blitz++ 1.0.2, reference BLAS/LAPACK 3.12, pybind11 3.1 and
CMake 4.4 with scikit-build-core 1.1.


Requirements

- Python 3.10 or later with its development headers.
- A C++ compiler supporting C++17 and a Fortran 77 compiler
  (e.g. g++ and gfortran).
- Blitz++ 0.9 or later.
- BLAS and LAPACK. If possible, use an optimised implementation
  (OpenBLAS, Intel MKL, ...) for maximum performance.

NumPy, Matplotlib and Pillow are installed by pip as dependencies; SciPy
(for RCLED, GARCLED and the dispersive material helpers) with the 'scipy'
extra. pybind11, CMake and Ninja are downloaded for the build when they
are missing.

On Debian or Ubuntu the system requirements can be installed with

  sudo apt install g++ gfortran python3-dev python3-venv python3-tk \
       libblitz0-dev libblas-dev liblapack-dev


Building and installing

The extension is built with CMake (CMakeLists.txt) through
scikit-build-core, so a plain pip install builds and installs it:

  python3 -m pip install .

CMake finds Python, pybind11, Blitz++ and BLAS/LAPACK by itself. For
libraries outside the system prefixes, put CMake settings (e.g.
CMAKE_PREFIX_PATH) in a local.cmake file next to CMakeLists.txt (see
local.cmake.example; local.cmake is not tracked).

Distributions that mark the system Python as externally managed
(PEP 668) require a virtual environment, e.g.

  python3 -m venv venv
  venv/bin/pip install .

For development, uv (https://docs.astral.sh/uv/) creates a virtual
environment with an editable install: 'uv sync'. After C++ or Fortran
changes, 'make dev' rebuilds incrementally in that environment.

The SCons build (SConstruct, machine_cfg.py) was replaced by CMake; the
Python 2-era INSTALL.MacOSX and INSTALL.Windows are kept for reference.


Testing

  cd testsuite
  python3 camfr_test.py

Set MPLBACKEND=Agg to run the tests without a display.
