Verions and Releases - galacticusorg/galacticus GitHub Wiki

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 big 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/buil$
' -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/Ga$
acticus/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-modul$
s-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]:$
PPFLAGS[-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 -DQ$
ULLAVAIL -DMATHEVALAVAIL]:FCCOMPILER_VERSION[Using built-in specs. COLLECT_GCC=gfortran COLLECT_LTO_WRAPPER=/home/abenson/Galacticus/Tools/libexec/gcc/x86_64-pc-linux-gnu/12.0.0/lto-wrapper Target: x86_64-pc-linux-gn$
 Configured with: ../gcc-git/configure --prefix=/home/abenson/Galacticus/Tools --disable-multilib --enable-languages=c,c++,fortran,lto Thread model: posix Supported LTO compression algorithms: zlib gcc version 12.0.0 
20211022 (experimental) (GCC) ]:CCOMPILER_VERSION[Using built-in specs. COLLECT_GCC=gcc COLLECT_LTO_WRAPPER=/home/abenson/Galacticus/Tools/libexec/gcc/x86_64-pc-linux-gnu/12.0.0/lto-wrapper Target: x86_64-pc-linux-gn$
 Configured with: ../gcc-git/configure --prefix=/home/abenson/Galacticus/Tools --disable-multilib --enable-languages=c,c++,fortran,lto Thread model: posix Supported LTO compression algorithms: zlib gcc version 12.0.0 
20211022 (experimental) (GCC) ]:CPPCOMPILER_VERSION[Using built-in specs. COLLECT_GCC=g++ COLLECT_LTO_WRAPPER=/home/abenson/Galacticus/Tools/libexec/gcc/x86_64-pc-linux-gnu/12.0.0/lto-wrapper Target: x86_64-pc-linux-$
nu Configured with: ../gcc-git/configure --prefix=/home/abenson/Galacticus/Tools --disable-multilib --enable-languages=c,c++,fortran,lto Thread model: posix Supported LTO compression algorithms: zlib gcc version 12.0$
0 20211022 (experimental) (GCC) ]
MM: <- Done task: report

The fb96dd63391b52e801e8c1059e6ece2ca433efd6 in the above is the Git revision has 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. Documentation (for both galacticus and analysis-perl repos) must build cleanly without any missing references;
  3. Test suites (for both galacticus and analysis-perl repos) must pass with no failures;
  4. Create releases on GitHub:
    1. galacticus, with assets:
      1. Statically-linked binary, galacticus.exe;
      2. Documentation PDFs.
    2. datasets release in GitHub;
    3. analysis-perl, with assets:
      1. Documentation PDF.
    4. galacticusDockerBuildEnv
  5. 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. Compiler 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.pl is provided. Static executables can be created using the following commands:
cd ~/galacticus
~/galacticus/scripts/build/staticRelinker.pl gfortran-11.2 `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.pl 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.pl gfortran-11.2 recfast.for -o recfast.exe -O3 -ffixed-form -ffixed-line-length-none

cd ~/datasets/dynamic/CAMB-1.3.2/fortran
~/galacticus/scripts/build/staticRelinker.pl gfortran-11.2 -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.pl gcc-11.2 -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.pl gfortran-11.2 -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/c17.02/source
~/galacticus/scripts/build/staticRelinker.pl g++-11.2 -O3 -ftrapping-math -fnop-math-errno -ftree-vectorize -Wall -g -o cloudy.exe maincl.o -L. -lcloudy
  1. 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
  1. Add galacticusExecutablesMacOS.zip to the GitHub release.