About This Manual

This is the user manual for \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\), a modern package for lattice simulations of the dynamics of interactive fields in an expanding Universe. This manual focuses on explaining how to use \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\), not on the theory and/or techniques behind the code. The theoretical basis for the equations implemented in \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\) can be found, instead, in our monographic series on lattice techniques, "The art of simulating the early Universe":

Part I. Integration techniques and canonical cases. (Ref. 1)

Part II. Non-canonical cases and gravitational waves. (Ref. 2)

Part III. Scalar-Gauge-Fluid dynamics. (Ref. 3)

which we refer to, colloquially, as \(\mathtt{The~Art-I}\), \(\mathtt{The~Art-II}\) and \(\mathtt{The~Art-III}\) monographs. Reading these reviews is however not mandatory in order to follow the manual, which is self-contained. Whenever lattice methods or theoretical results are quoted in this manual without explanation, the user will be referred to the corresponding part(s) of the monographs, where appropriate clarifications and/or demonstrations can be found. Having these monographs at hand, might therefore prove to be useful, so brief descriptions of their content and links to download them, are given in Lattice-Cosmology Reviews, inside the Theoretical Framework tab.

The present manual is structured as follows (click any chapter for its full description):

Start here

Introduction code structure, features, and the field equations being solved

Provides an overview on \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\), introducing the file structure of the code, and the continuum version of the field equations, as well as features/capabilities of the code, that successive versions of \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\) have gone incorporating in time. This section applies to all versions of \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\), and we strongly recommend newcomers to read it.

First physics module

Scalar-Scalar Interactions your first run: compile, define a model, set parameters, read the output

Presents all necessary steps to run an example model with interacting singlet scalar fields. This chapter is particularly relevant for a newbie, as we introduce the concept of program variables, relevant for choosing appropriate re-scalings of both field and space-time variables, and we review how to compile and run \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\), how to define a new model, how to introduce the different parameters of the simulation, and how to interpret the output produced by the code. This section applies to all versions of \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\).

More physics modules

Scalar-Gauge Dynamics scalars charged under Abelian U(1) and non-Abelian SU(2) symmetries

Explains how to simulate models with scalar fields interacting among themselves and charged under a U(1) gauge symmetry (and hence interacting also with Abelian gauge fields), and under a SU(2) gauge symmetry [and thus interacting also with non-Abelian SU(2) gauge fields]. This section applies to all versions of \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\).

Axion-Gauge Dynamics an axion-like particle coupled to a gauge sector via \(\phi F\tilde F\)

Discusses how to simulate scenarios in \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\) where there are an axion-like particle (ALP) and an Abelian gauge sector, interacting through the coupling \(\phi F\tilde F\). This section requires \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\) version 2.0 or above.

Cosmic Defects cosmic strings and domain walls, and how to reach scaling faster

Discusses how the creation of cosmic defects can be studied with \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\). We explain techniques to accelerate the achievement of scaling in a cosmic defect network (in particular for cosmic strings and domain walls), and also introduce specific observables for each type of defect. This section requires \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\) version 2.0 or above.

Non-minimal Scalar Fields Dynamics non-minimal couplings to gravity and non-canonical kinetic terms

Expands over previous sections on scalar fields, explaining how \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\) can also deal with non-canonical interactions of scalar fields, either non-minimally coupled to gravity via \(\phi^2 R\), or with non-minimal kinetic terms, \(\mathcal{G}_{ab}\partial_{\mu}\phi_a \partial^{\mu}\phi_b\). This section requires \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\) version 2.0 or above.

Gravitational Wave Dynamics the gravitational waves sourced by your scalar/gauge simulation

Explains how to use the gravitational wave (GW) module of \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\), so that the production of GWs can be computed in simulations with scalar and/or gauge fields. While this section is suitable for versions 1.1, 1.2 and 1.3 of the code, we recommend to use instead \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\) version 2.0 or above.

Setup & internals

Initial Conditions how the initial field fluctuations are set, including arbitrary spectra

Explains how to set up the initial condition of the different fields that \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\). This includes arbitrary spectra of scalar and/or gauge fields, and in the case of scalar-gauge theories (Abelian U(1) Scalar-Gauge Dynamics and Non-Abelian SU(2) Scalar-Gauge Dynamics). This section applies to all versions of \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\), though different features or field content requires different code versions, as we will indicate in each case.

Output Observables the quantities measured during a run: energies, spectra, and more

Describes the different observables that \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\) can measure and output during a simulation, such as field averages, energy densities, and power spectra, as well as how to configure which ones are computed and how often. This section applies to all versions of \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\).

Simulations in (2+1) and (1+1) dimensions scalar field dynamics on lower-dimensional lattices

Explains how to simulate scalar field dynamics in (2+1) and (1+1) dimensions. This section requires \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\) version 2.0 or above.

What \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\) does in detail under the hood: initialization, evolution algorithms, observables

Elaborates on the physics captured by \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\), including details on how fields are initialized, how the equations of motion are solved, and what are the relevant observables that can be measured in a run. This section applies to all versions of \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\).

Parallelization, Fourier Transforms, HDF5: Output and Backups & Expression Templates running on many cores, fast Fourier transforms, output/backups, and the expression-template engine

Describe some of the technical features implemented in \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\), including its parallel support, Fourier transform routines, back-up options, and the expression-template engine underlying the code. These sections apply to all versions of \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\).

Important Note: CosmoLattice updates & versions

\(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\) is an ever-evolving package, and improved features are continuously being added. We typically release publicly a new version of the code whenever either of the following aspects take place: code algorithm improvements, new lattice methods, or new physics modules. Successive versions of the code with new lattice methods and/or new physics modules, will always maintain previous lattice methods and physics modules, simply adding the new ingredients. However, updated versions with new algorithmic improvements, might supersede (and hence substitute) previous parts of the code. The latter typically concern the very internal tripes of \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\), as e.g. the Fourier transform or internal communication between cores in a cluster, which the majority of users will never touch. Details of the different versions of the code can be found in the \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\) Version Guide. This manual can be approached, in any case, independently of the version of \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\) that the reader is using or intending to use. Most sections of the manual are common to all \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\) versions, and whenever new physics modules and/or features presented in the manual require specific versions of the code, this will be clearly specified. We recommend, at any rate, to download and work always with the latest version of \(\mathcal{C}\mathtt{osmo}\mathcal{L}\mathtt{attice}\) (currently version 2.0, released on July 2026).

The manual is also complemented with a few reference pages:

Installation Parameters Variable Names CMake Flags Input File Builder

  1. D. G. Figueroa, A. Florio, F. Torrenti, and W. Valkenburg. The art of simulating the early universe – part i: integration techniques and canonical cases. JCAP, 04:035, 2021. arXiv:2006.15122, doi:10.1088/1475-7516/2021/04/035. ↩

  2. J. Baeza-Ballesteros, D. G. Figueroa, A. Florio, J. Lizarraga, N. Loayza, K. Marschall, T. Opferkuch, B. A. Stefanek, F. Torrentí, and A. Urio. The art of simulating the early universe. part ii. non-canonical cases & gravitational waves. JCAP, 06:087, 2026. arXiv:2512.15627, doi:10.1088/1475-7516/2026/06/087. ↩

  3. D. G. Figueroa, K. Marschall, A. Midiri, and A. Roper Pol. The art of simulating the early universe. part iii. scalar-gauge-fluid dynamics. JCAP (submitted ), XX:YYY, 2026. arXiv:2606.XYZYZXY, doi:ZZZZ. ↩