ParaToric

ParaToric is a C++ package that implements a continuous-time quantum Monte Carlo algorithm for the toric code in a parallel field (aka the extended/perturbed toric code)

$$\hat{\mathcal{H}}_{\mathrm{eTC}} = \underbrace{- \mu \sum_+ \prod_{l \in +} \hat{\sigma}_l^x \; - J \sum_{\square} \prod_{l \in \square} \hat{\sigma}_l^z}_{\text{toric code } (\text{square lattice, } \mu=J=1)} \; \underbrace{- h \sum_{l} \hat{\sigma}_l^x \; - \lambda \sum_{l} \hat{\sigma}_l^z}_{\text{external fields}},$$

where $J, \lambda \geq 0$ in the $\hat{\sigma}^x$-basis and $\mu, h \geq 0$ in the $\hat{\sigma}^z$-basis. The temperature $T=1 / \beta$ is finite. We implement many lattice geometries, see Usage.

If you use ParaToric for a publication, please cite Linsel et al., SciPost Phys. Codebases 75 (2026), Linsel et al., SciPost Phys. Codebases 75-r1.0 (2026), and the original algorithm paper Wu et al., Phys. Rev. B 85, 195104 (2012).

Dependencies

We require a C++ compiler (tested with GCC 15 and Clang 20) with C++23 support. Our implementation further requires the Boost (1.87 and above) and HDF5 (1.14.3 and above) libraries. Refer to their website for installation instructions.

If you intend to use our Python scripts, you will need NumPy, matplotlib and h5py.

Quickstart (CLI)

To compile this project, run the following command:

$ cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DPARATORIC_ENABLE_NATIVE_OPT=ON -DPARATORIC_LINK_MPI=ON -DPARATORIC_BUILD_CLI=ON
$ cmake --build build -jN
$ ctest --test-dir build -jN --output-on-failure
$ cmake --install build

Replace N with the number of cores you want to use, e.g. -j4 for 4 cores.

By default, the executables will be installed in ${CMAKE_SOURCE_DIR}/${CMAKE_INSTALL_BINDIR}/, the header files in ${CMAKE_INSTALL_INCLUDEDIR}/paratoric and the static libraries in ${CMAKE_SOURCE_DIR}/${CMAKE_INSTALL_LIBDIR}/. By default, CMAKE_INSTALL_PREFIX = CMAKE_SOURCE_DIR, since on a computing cluster users may not have privileges to install software into the usual Linux/Unix folders. The Python scripts that come with this package expect ${CMAKE_SOURCE_DIR}/bin/, this directory always contains the executable paratoric in any case. If you want to install paratoric into a custom directory, pass this directory to CMake using the -DCMAKE_INSTALL_PREFIX flag. E.g., if you wanted to install into /usr/local/, you would use cmake -DCMAKE_INSTALL_PREFIX=/usr/local/ .. instead of cmake ...

Usage (Python CLI)

There are five ways to use ParaToric. We provide bindings to C/C++/Python and command line interfaces for C++/Python, see documentation. Here we only briefly present the Python command line interface.

A Jupyter notebook for creating SLURM jobscripts is provided.

General Python command line options

Long flag	Short	Description
`--help`	`-h`	Display help message (lists command line arguments)
`--simulation`	`-sim`	Simulation type
`--N_thermalization`	`-Nth`	Number of thermalization steps (i.e. proposed updates)
`--N_samples`	`-Ns`	Number of samples
`--N_between_steps`	`-Nbs`	Number of steps between samples
`--N_resamples`	`-Nr`	Number of bootstrap resamples
`--custom_therm`	`-cth`	Whether thermalization values of $h$ and $\lambda$ should be used (`0` or `1`)
`--observables`	`-obs`	List of observables, e.g. `fredenhagen_marcu percolation_probability energy`
`--seed`	`-seed`	Seed for the pseudorandom number generator. `0` means random seed
`--mu_constant`	`-muc`	Value of $\mu$
`--J_constant`	`-Jc`	Value of $J$
`--h_constant`	`-hc`	Value of $h$
`--h_constant_therm`	`-hct`	Thermalization value of $h$
`--lmbda_constant`	`-lmbdac`	Value of $\lambda$
`--lmbda_constant_therm`	`-lmbdact`	Thermalization value of $\lambda$
`--output_directory`	`-outdir`	Output directory
`--snapshots`	`-snap`	Whether snapshots should be saved to output directory (`0` or `1`)
`--full_time_series`	`-fts`	Whether full time series should be saved to output directory (`0` or `1`)
`--processes`	`-proc`	Number of (logical) CPU cores for Python multiprocessing

Lattice specific Python command line options

Long flag	Short	Description
`--help`	`-h`	Display help message (lists command line arguments)
`--basis`	`-bas`	Spin basis (`x`, `z`)
`--lattice_type`	`-lat`	Lattice type (e.g. `square`, `cubic`, `triangular`, `honeycomb`, ...)
`--system_size`	`-L`	System size (`20` will result in $20 \times 20$ lattice in 2D)
`--temperature`	`-T`	Temperature $T=1 / \beta > 0$
`--boundaries`	`-bound`	Boundary conditions (`periodic` or `open`)
`--default_spin`	`-dsp`	Default initialization value of spin on edges (`1` or `-1`)

It is relatively easy to define your own lattices/boundary conditions by adapting the code. Observables may have to be adapted, too! This is especially relevant for all percolation observables and Wilson/'t Hooft loops. Make sure to write appropriate test cases.

$T$-sweep

This simulation type runs T_steps individual Markov chains for evenly spaced temperatures in the interval T_lower $\leq T \leq$ T_upper. It calculates and plots observables for all temperatures. As this task is trivial to parallelize, we advise matching processes = T_steps as closely as possible for optimal runtime.

An exemplary simulation could look like this:

$ python3 ./python/cli/paratoric.py -sim etc_T_sweep -Nbs 8000 -Ns 1000 -muc 1 -Nth 50000 -Tl 0.1 -Tu 10 -Ts 15 -hc 0.5 -Jc 1 -lmbdac 0.2 -Nr 1000 -obs percolation_strength percolation_probability largest_cluster largest_plaquette_cluster string_number energy energy_h energy_mu energy_J energy_lmbda sigma_x sigma_z star_x plaquette_z staggered_imaginary_times delta anyon_count anyon_density fredenhagen_marcu sigma_x_static_susceptibility sigma_x_dynamical_susceptibility sigma_z_static_susceptibility sigma_z_dynamical_susceptibility -bas x -lat square -L 6 -bound periodic -dsp 1 -outdir /your/output/directory