Versions and Releases

Semantic Versioning

Galacticus follows the concepts of semantic versioning, such that version numbers are of the form X.Y.Z where X, Y, and Z are integers which are incremented according to the following rules:

  1. The major version, X, is incremented when incompatible API changes are made;

  2. The minor version, Y, is incremented when adding functionality that is backward compatible; and,

  3. The patch version, Z, is incremented when a backwards compatible bug fix is made.

The “API” for Galacticus consists of:

  1. Inputs:

    1. The parameter file passed to Galacticus on the command line;

    2. Any data files (e.g. merger tree files) used by Galacticus.

  2. Outputs:

    1. The main output HDF5 file;

    2. Any auxiliary files that are output.

Changes to the format or syntax of any of these files are considered to incompatible API changes. Note that additions to the formats that don’t break backward compatibility (e.g. adding a new class with new parameters) are backwards compatible and so do not require a major version increment.

Versions are implemented through GitHub’s “release” mechanism, and so are based on git “tags”. Associated with each release are a statically-linked binary executable and documentation. Additionally a Docker image is built for each version, which can be retrieved using docker pull galacticusorg/galacticus:X.Y.Z.

The Galacticus datasets repo has corresponding versions - it’s recommended to using matching versions of the galacticus and datasets repos.

Determining the Exact Version Used

You can determine the exact version (i.e. the Git revision hash) of a Galacticus executable by using the report task. To do this, simply run the parameter file report.xml:

./Galacticus.exe parameters/report.xml

You will see output similar to:

              ##
   ####        #                  #
  #   #        #             #
 #       ###   #  ###   ### ###  ##   ### ## ##   ##
 #       #  #  #  #  # #  #  #    #  #  #  #  #  #
 #   ###  ###  #   ### #     #    #  #     #  #   #
  #   #  #  #  #  #  # #     #    #  #     #  #    #
   ####  #### ### ####  ###   ## ###  ###   #### ##

 © 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016,
   2017, 2018, 2019, 2020, 2021, 2022
   - Andrew Benson

MM: -> Begin task: report
MM:     This is Galacticus: revision fb96dd63391b52e801e8c1059e6ece2ca433efd6   (branch: master; build time: Sun Oct 23 16:13:16 UTC 2022)
MM:     Built with: :GSL_version[2.6]:FoX_version[4.1.2]:HDF5_version[1.8.9]:FCCOMPILER[gfortran]:PREPROCESSOR[cpp]:CCOMPILER[gcc]:CPPCOMPILER[g++]:FCFLAGS[-ffree-line-length-none -frecursive -DBUILDPATH='./work/build' -J./work/build/moduleBuild/ -I./work/build/ -fintrinsic-modules-path /home/abenson/Galacticus/Tools/finclude -fintrinsic-modules-path /home/abenson/Galacticus/Tools/include -fintrinsic-modules-path /home/abenson/Galacticus/Tools/include/gfortran -fintrinsic-modules-path /home/abenson/Galacticus/Tools/lib/gfortran/modules -L/home/abenson/Galacticus/Tools/lib -L/home/abenson/Galacticus/Tools/lib64 -pthread -Wall -fbacktrace -ffpe-trap=invalid,zero,overflow -fdump-core -O3 -ffinite-math-only -fno-math-errno -fopenmp -g -DPROCPS -DOFDUNAVAIL -DFFTW3AVAIL -DANNAVAIL -DQHULLAVAIL -DMATHEVALAVAIL]:FCFLAGS_NOOPT[-ffree-line-length-none -frecursive -DBUILDPATH='./work/build' -J./work/build/moduleBuild/ -I./work/build/ -fintrinsic-modules-path /home/abenson/Galacticus/Tools/finclude -fintrinsic-modules-path /home/abenson/Galacticus/Tools/include -fintrinsic-modules-path /home/abenson/Galacticus/Tools/include/gfortran -fintrinsic-modules-path /home/abenson/Galacticus/Tools/lib/gfortran/modules -L/home/abenson/Galacticus/Tools/lib -L/home/abenson/Galacticus/Tools/lib64 -pthread -Wall -fbacktrace -ffpe-trap=invalid,zero,overflow -fdump-core -g]:CFLAGS[-fopenmp -DBUILDPATH='./work/build' -I./source/ -I./work/build/ -I/home/abenson/Galacticus/Tools/include -g -DOFDLOCKS -DPROCPS -DOFDUNAVAIL]:CPPFLAGS[-fopenmp -DBUILDPATH='./work/build' -I./source/ -I./work/build/ -I/home/abenson/Galacticus/Tools/include -I/home/abenson/Galacticus/Tools/include/libqhullcpp -g -DOFDLOCKS -DPROCPS -DOFDUNAVAIL -DANNAVAIL -DQHULLAVAIL -DMATHEVALAVAIL]:FCCOMPILER_VERSION[...]
MM: <- Done task: report

The fb96dd63391b52e801e8c1059e6ece2ca433efd6 in the above is the Git revision hash from which this copy of Galacticus was built.

Release Steps

  1. Both MPI and non-MPI builds must compile cleanly without errors or warnings;

  2. Create releases on GitHub:

    1. galacticus, with assets:

      1. Statically-linked binary, galacticus.exe.

      Note

      The LaTeX/PDF manuals have been retired. Documentation is now published automatically on ReadTheDocs, so there are no documentation PDFs to build or attach as release assets.

    2. datasets release in GitHub;

    3. galacticusDockerBuildEnv

  3. Add archives of external dependencies to the GitHub release. Currently these are:

    1. CAMB

      1. plus forutils

    2. RecFast

    3. FSPS

    4. Cloudy

    5. FFTLog

    6. FoX

    7. ANN

    8. libmatheval

    9. FFTW3

    10. HDF5

    11. gfortran

    12. GSL

    13. Guile

Docker images can be built locally following the instructions here.

Docker images can be exported as follows:

sudo docker pull ghcr.io/galacticusorg/buildenv:latest
sudo docker run --name buildenvV1.0.0 galacticusorg/buildenv
sudo docker export --output="/home/abensonca/Scratch/galacticusorg_buildenv_v1.0.0.tar" buildenvV1.0.0
sudo docker stop buildenvV1.0.0
sudo bzip2 galacticusorg_buildenv_v1.0.0.tar

MacOS Binaries

Compilation instructions for MacOS are given here. To create statically-linked binaries on MacOS proceed as follows:

  1. Compile Galacticus as usual.

  2. Run ./Galacticus.exe parameters/buildTools.xml to build all run-time tools (RecFast, FSPS, CAMB, Class, Cloudy).

  3. Since MacOS does not really support static-linking we need to do some manual re-linking to making statically linked binaries. To make this easier a script ./scripts/build/staticRelinker.py is provided. Static executables can be created using the following commands:

    cd ~/galacticus
~/galacticus/scripts/build/staticRelinker.py gfortran-16 `cat ./work/build/Galacticus.d` ./work/build/Galacticus.parameters.o ./work/build/Galacticus.md5s.o -o Galacticus.exe -ffree-line-length-none -frecursive -DBUILDPATH=\'./work/build\' -J./work/build/moduleBuild/ -I./work/build/ -fintrinsic-modules-path /usr/local/include -L/usr/local/lib -L/opt/local/lib -fintrinsic-modules-path /usr/local/finclude -fintrinsic-modules-path /usr/local/include/gfortran -fintrinsic-modules-path /usr/local/include -fintrinsic-modules-path /usr/lib/gfortran/modules -fintrinsic-modules-path /usr/include/gfortran -fintrinsic-modules-path /usr/include -fintrinsic-modules-path /usr/finclude -fintrinsic-modules-path /usr/lib64/gfortran/modules -fintrinsic-modules-path /usr/lib64/openmpi/lib -pthread -Wall -fbacktrace -ffpe-trap=invalid,zero,overflow -fdump-core -O3 -ffinite-math-only -fno-math-errno -fopenmp -g -DOFDUNAVAIL -DFFTW3AVAIL -DANNAVAIL -DMATHEVALAVAIL `./scripts/build/libraryDependencies.py Galacticus.exe -ffree-line-length-none -frecursive -DBUILDPATH=\'./work/build\' -J./work/build/moduleBuild/ -I./work/build/ -fintrinsic-modules-path /usr/local/include -L/usr/local/lib -L/opt/local/lib -fintrinsic-modules-path /usr/local/finclude -fintrinsic-modules-path /usr/local/include/gfortran -fintrinsic-modules-path /usr/local/include -fintrinsic-modules-path /usr/lib/gfortran/modules -fintrinsic-modules-path /usr/include/gfortran -fintrinsic-modules-path /usr/include -fintrinsic-modules-path /usr/finclude -fintrinsic-modules-path /usr/lib64/gfortran/modules -fintrinsic-modules-path /usr/lib64/openmpi/lib -pthread -Wall -fbacktrace -ffpe-trap=invalid,zero,overflow -fdump-core -O3 -ffinite-math-only -fno-math-errno -fopenmp -g -DOFDUNAVAIL -DFFTW3AVAIL -DANNAVAIL -DMATHEVALAVAIL`

cd ~/datasets/dynamic/RecFast
~/galacticus/scripts/build/staticRelinker.py gfortran-16 recfast.for -o recfast.exe -O3 -ffixed-form -ffixed-line-length-none

cd ~/datasets/dynamic/CAMB-1.3.2/fortran
~/galacticus/scripts/build/staticRelinker.py gfortran-16 -cpp -Ofast -fopenmp -fintrinsic-modules-path /usr/local/include -L/usr/local/lib -L/opt/local/lib -JRelease -IRelease/ -I"Users/ajb/datasets/dynamic/CAMB-1.3.2/fortran/../forutils/Release/" Release/inidriver.o Release/libcamb.a  -L"/Users/ajb/datasets/dynamic/CAMB-1.3.2/fortran/../forutils/Release/" -lforutils -o camb

cd ~/datasets/dynamic/class_public-3.0.2
~/galacticus/scripts/build/staticRelinker.py gcc-16 -O3 -fopenmp -g -fPIC -o class build/growTable.o build/dei_rkck.o build/sparse.o build/evolver_rkck.o build/evolver_ndf15.o build/arrays.o build/parser.o build/quadrature.o build/hyperspherical.o build/common.o build/trigonometric_integrals.o build/input.o build/background.o build/thermodynamics.o build/perturbations.o build/primordial.o build/fourier.o build/transfer.o build/harmonic.o build/lensing.o build/distortions.o build/wrap_recfast.o build/injection.o build/noninjection.o build/hyrectools.o build/helium.o build/hydrogen.o build/history.o build/wrap_hyrec.o build/energy_injection.o build/output.o build/class.o -lm

cd ~/datasets/dynamic/fsps-3.2/src
~/galacticus/scripts/build/staticRelinker.py gfortran-16 -O3 -cpp -fPIC -mcmodel=medium  -o autosps.exe autosps.o sps_vars.o sps_utils.o compsp.o csp_gen.o galacticus_IMF.o ssp_gen.o getmags.o locate.o funcint.o sps_setup.o pz_convol.o get_tuniv.o intsfwght.o imf.o imf_weight.o add_dust.o getspec.o sbf.o add_bs.o mod_hb.o add_remnants.o getindx.o smoothspec.o mod_gb.o add_nebular.o write_isochrone.o sfhstat.o linterp.o tsum.o add_agb_dust.o linterparr.o ztinterp.o vacairconv.o igm_absorb.o get_lumdist.o attn_curve.o sfh_weight.o sfhlimit.o sfhinfo.o setup_tabular_sfh.o agn_dust.o

cd ~/datasets/dynamic/c23.01/source
~/galacticus/scripts/build/staticRelinker.py g++-16 -O3 -ftrapping-math -fnop-math-errno -ftree-vectorize -Wall -g -o cloudy.exe maincl.o -L. -lcloudy

  4. Package the executables (and data):

    zip -r galacticusExecutablesMacOS.zip galacticus/Galacticus.exe datasets/dynamic/fsps-3.2 datasets/dynamic/class_public-3.0.2 datasets/dynamic/CAMB-1.3.2 datasets/dynamic/RecFast datasets/dynamic/c17.02

  5. Add galacticusExecutablesMacOS.zip to the GitHub release.