The example Windows installation described below was done on the following system:
Machine: x64-based PC laptop
Operating system: Windows 10 Education
Processor: Intel Core i9, 2500 MHz, 14 cores
RAM: 32 GB

OPTION 1: Download as zip file:

1. Go to https://github.com/LGalaxiesPublicRelease/LGalaxies2020_PublicRepository
2. Click the green "Code" drop-down menu, and select "Download ZIP" [~42.2 MB]
3. Move the downloaded file (master.zip) to a suitable base directory.
4. Using any un-zipping software (e.g. 7-Zip, or other), extract the model into a folder called /LGalaxies2020_PublicRepository-master, hereafter, the "project root directory"
5. Manually add an empty /output folder in the project root directory

OPTION 2: Download as a local Git repository:
This option requires having a GitHub account as well as Git and Git Bash on your Windows system. To download and install Git and Git Bash, follow the instructions at: https://github.com/git-guides/install-git Once you have Git and a GitHub account, proceed as follows:

1. Open Git Bash
2. Navigate to a directory where you'd like L-Galaxies kept:
• cd [PATH TO CHOSEN FOLDER]
3. Clone the repository:
• git clone https://github.com/[GITHUB_USERNAME]/https://github.com/LGalaxiesPublicRelease/LGalaxies2020_PublicRepository

OPTION 3: Download as a local Git repository via the Eclipse IDE:
The L-Galaxies 2020 code can also be obtained from GitHub via the Eclipse IDE, which offers a more intuitive way of editing and debugging code using a Graphical User Interface (GUI). To install L-Galaxies 2020 this way, skip straight to STEP 8 below, where information on how to install Eclipse and synchronise it with L-Galaxies 2020 is provided.

1. Download the standard SpecPhotTables [~1.6 GB] [direct download]
2. Move the downloaded .tar file (SpecPhotTables.tar) into the project root directory.
3. Navigate to the project root directory.
4. Unzip the file (using e.g. 7-Zip, or other)
This will create a folder called /SpecPhotTables containing the downloaded spectrophotometic tables
5. Download the treefiles (choose one of the following options):
Millennium-I:
• Treefile 5 [~804 MB] [direct download]
• Treefiles 0-9 [~7.5 GB] [direct download]
• Treefiles 0-511 [~401 GB] [direct download]
Millennium-II:
• Treefiles 40-79 [~6.3 GB] [direct download]
• Treefiles 0-511 [~92 GB] [direct download]
6. Move the downloaded .tar file into the /MergerTrees directory, which is in the project root directory.
7. Navigate to the /MergerTrees.
8. >Unzip the treefiles
This will create a folder called either /MR/treedata, /MRII/treedata, or /MRII containing the downloaded treefiles.

NOTE: Because the full set of Millennium-I treefiles (MR_allMergerTrees.tar) are stored at an "http" address, rather than "https", some browsers may prevent it from being downloaded automatically. To get around this (at least in Chrome), right-click the download link above, select "Save link as..." and confirm a destination folder. Then, if the browser says that the file "can't be downloaded securely", click the up arrow next to the download and select "Keep".

L-Galaxies requires a C compiler (e.g. gcc), the make command, and the GNU Scientific Libraries (GSL) to run. Most Windows distributions do not come these by default. If yours doesn't, the simplest solution is to download them via a Linux emulator. Here, we provide instructions for installing the popular gcc compiler via Cygwin. Other compilers (e.g. icc) and Linux emulators (e.g. MinGW) are also available.

1. Go to: https://cygwin.com/install.html
2. Click "setup-x86_64.exe" [~1.4 MB]
3. Once downloaded, execute setup-x86_64.exe and begin following the instructions to install to the default location: C:\tools\cygwin
4. In "Select packages", choose the "Full" view
5. Select the following additional packages:
   • gcc-core 11.3.0-1 [~30.7 MB]
   • gcc-debuginfo 11.3.0-1 [~32.4 MB]
   • gsl 2.3-2 [~58 KB]
   • gsl-debuginfo 2.3-2 [~2.2 MB]
   • make 4.3-1 [~503 KB]
   • make-debuginfo 3.3-1 [~441 KB]
6. Click "next"
7. Click "next" again to complete the installation

N.B. We recommend you keep the setup-x86_64.exe installer on your system, as it can be run at any time to add/remove/update Cygwin tools.

The L-Galaxies 2020 makefile needs to be told which C compiler to use and where the GSL libraries are stored. This information is provided by the user as a SYSTYPE configuration in the My_Makefile_compilers file, located in the project root directory.

SYSTYPE = "Linux" at the top of the file and un-commenting SYSTYPE = "cygwin". This set-up should be suitable for most Windows installations. It assumes the gcc compiler is to be used and that the GSL header files and libraries are stored in their default locations: /usr/local/include and /usr/local/lib (which is where cygwin should have put them). If your GSL files are not stored in these locations, you will need to change the GSL_INCL and GSL_LIBS paths accordingly. By default, no compiler optimisation flags are added to this configuration. Feel free to add ones of your own, if you wish.

You can check that gcc and gsl is installed on your system by executing the following commands in a cygwin64 terminal:

• cygcheck -cd | grep gcc
• cygcheck -cd | grep gsl

Common compiler issues

1. Running with an old C standard: If your distribution is quite old, it may not be running with the latest C standard. If so, you may need to inform the compiler of this in My_Makefile_compilers by adding the -std flag to the CC call. (e.g. CC = gcc -std=C99 for systems running with C99).


2. Running with old C libraries: Likewise, an old distribution may not have a version of the GNU C libraries (glibc). If so, you may need to install and build new C libraries following the instructions provided here (which is compilcated!). Alternatively, a quick hack (if you do have a recent version of the GSL libraries, see above), is to replace the #include <math.h> statements at the top of each L-Galaxies code .c file with #include <gsl/gsl_math.h>


3. Multiple tentative definitions: If a compilation crashes with an error stating that "multiple tenative definitions of a global variable in different compilation units" are not allowed, you may need to add the -fcommon flag to the CC call in My_Makefile_compilers. Note that this flag is set by default when running with SYSTYPE = "cygwin".


4. Shared libraries: If your system has shared GSL libraries (i.e. .so files), rather than local archived ones (i.e. .a files), you may need to replace the default -static flag for GSL_LIBS in My_Makefile_compilers with a -shared flag. You may also find that the GSL libraries are stored in /usr/include and /usr/lib (rather than /usr/local/include and /usr/local/lib), so should update the paths in My_Makefile_compilers accordingly.


5. Shared object errors: Similarly, if you are getting errors like: "Relocation R_X86_64_32 against undefined symbol '[LGALAXIES_PARAMETER]' can not be used when making a shared object", then you may need to add the -fPIC flag to the CC call in My_Makefile_compilers

Compiling and running L-Galaxies 2020 is done as follows:

1. In a cygwin64 terminal, navigate to the project root directory
2. Compile the code:
• make
3. Run the code:
• ./L-Galaxies ./input/[INPUT FILE]

There are four standard input files to choose from (for info on which to use, see STEP 7):

• input_MR_W1_PLANCK_LGals2020_DM.par
• input_MR_W1_PLANCK_LGals2020_MM.par
• input_MRII_W1_PLANCK_LGals2020_DM.par
• input_MRII_W1_PLANCK_LGals2020_MM.par

Once L-Galaxies 2020 has finished running, the output file(s) generated will be stored in the /outputs folder. These can be read in to python for analysis as described in STEP 6.

Straight out of the box, L-Galaxies 2020 will run on treefile 5 of Millennium-I with only redshift 0 data outputted. However, various other standard set-ups are also possible (see STEP 7).

By default, L-Galaxies 2020 outputs are written as binary files. To be read, binary files require prior knowledge of the structure of the data in the file. This is why default L-Galaxies output structures (compatible for python) are provided in the /AuxCode/awk/output/python folder (see "Changing which properties are outputted" in STEP 7).

L-Galaxies 2020 also comes with a set of simple python scripts to read output files (according to the output structure), convert properties from code units to physical units, select sub-samples, plot a few key relations, etc. These python scripts can be found in /AuxCode/Python.

To run the scripts on the default output produced by L-Galaxies 2020, simply execute the main_lgals.py file in python. This will generate a pickled version of the L-Glaxies 2020 output (.npy file) in the /output folder, as well as some plots of key galaxy population relations in the /figures folder. main_lgals.py also contains a number of switches which can be used to modify how/what data is read-in and plotted.

For more information on how to use/modify these python scripts, feel free to speak to me at the workshop, or drop me an email (r.yates3 -at- herts.ac.uk).

(For those who prefer to handle data in IDL, there are some IDL scripts available for reading-in/plotting L-Galaxies outputs. If you are interested in getting a copy of these, feel free to speak to me at the workshop, or drop me an email.)

Default vs. Modified model
Input files (i.e. the .par files) are provided for the Default Model (DM) and Modified Model (MM) versions of L-Galaxies 2020 (see the discussion in Yates+21a for details). In brief, the Default Model allows the majority of material released by supernovae and stellar winds to mix with the ambient ColdGas before some is blown out as galactic winds. The Modified Model allows the majority of this newly-released material to be directly ejected into the surrounding HotGas, without first mixing with the ColdGas. Depending on which model you want to use, the corresponding input file is one of the following:

• input_MR_W1_PLANCK_LGals2020_DM.par
• input_MR_W1_PLANCK_LGals2020_MM.par

Note that these input files are for runs on the Millenium-I merger trees. If you want to run on Millennium-II instead, see below.

Millennium-I vs. Millennium-II
By default, L-Galaxies 2020 will try to run on Millennium-I merger trees. To switch to Millennium-II, make sure you've downloaded some Millennium-II treefiles (see STEP 2), and then do the following:

1. Open the My_Makefile_options file in the project root directory
2. Uncomment the MRII switch
3. Save and close My_Makefile_options
4. Use the default model (DM) or modified model (MM) Millennium-II input files as the argument when running the code (see STEP 5 above):
• input_MRII_W1_PLANCK_LGals2020_DM.par
• input_MRII_W1_PLANCK_LGals2020_MM.par

Snapshot vs. Galaxytree mode
Snapshot mode (the default for L-Galaxies 2020) will only output data for a user-defined set of redshifts (i.e. snapshots). Galaxytree mode will instead output data from all snapshots, along with the IDs needed to link a given galaxy to its progenitors and descendents (note that this generates much larger output files).

To use/modify snapshot mode:

1. Open desired_output_redshifts.txt in the /inputs folder
2. Add the redshifts you wish to be outputted to the top of this file, one on each line, with an empty line at the end of your list (L-Galaxies will match these to their nearest snapshots automatically)
3. Open the My_Makefile_options file in the project root directory
4. Set the NOUT parameter to equal the number of redshifts you set to be outputted in desired_output_redshifts.txt
5. Make sure that the GALAXYTREE switch is commented-out
6. Save and close My_Makefile_options
7. Compile and run L-Galaxies 2020 as described in STEP 5

To use galaxytree mode:

1. Open the My_Makefile_options file in the project root directory
2. Uncomment the GALAXYTREE switch
3. Save and close My_Makefile_options
4. Compile and run L-Galaxies 2020 as described in STEP 5

Changing the output file name

1. Open the input file you wish to use (see above) in the /inputs folder
2. Change FileNameGalaxies to an appropriate name. This will be the prefix in the name of the output file(s) that L-Galaxies generates.
3. Save and close the input file
4. Compile and run L-Galaxies 2020 as described in STEP 5

Changing the treefiles used

1. Open the input file you wish to use (see above) in the /inputs folder
2. Set FirstFile to the first treefile you wish to use
3. Set LastFile to the last treefile you wish to use
4. Save and close the input file
5. Compile and run L-Galaxies 2020 as described in STEP 5

To run L-Galaxies 2020 on the full set of Millennium-I or II trees, set FirstFile to 0 and LastFile to 511. For testing purposes on Millennium-I, treefile 5 alone is normally sufficient. For quick but statistically-significant runs on Millennium-I, treefiles 0-9 are normally sufficient. For quick but statistically-significant runs on Millennium-II, treefiles 40-79 are normally sufficient.

Model switches
L-Galaxies 2020 comes with a series of pre-defined model options (or "switches") that change e.g. the physics models used, the treefiles used, which properties are tracked/outputted, etc. These switches are defined in the My_Makefile_options file in the project root directory. There meanings should be quite self explanatory, but if you are unsure, feel free to ask! You are also able to add your own switches to your version of the code. These should be defined in My_Makefile_options and then utilised in the necessary code files via "ifdef statements" (or equivalent). For example, to create a switch which prevents the property BulgeMassRings from being outputted:

1. Open My_Makefile_options in the project root directory
2. Add the following line:
• OPT += -DNO_BULGEMASSRINGS_OUTPUT
3. Save and close My_Makefile_options
4. Put the following ifdef statement around the instances of BulgeMassRings in h_galaxy_output.h and save.c (see below for more details):
• #ifndef NO_BULGEMASSRINGS_OUTPUT
• ...
• #endif //NO_BULGEMASSRINGS_OUTPUT
5. Save and close the code files
6. Open the output structure you are using (e.g. LGalaxy_snapshots.py, LGalaxy_galtree.py, or one you have created yourself)
7. Remove BulgeMassRings by either setting it to "False" in the properties_used dictionary (at the bottom of the .py file), or directly commenting it out:
   • # ('BulgeMassRings',numpy.float32,12),

Changing which properties are outputted
By default (i.e. when in snapshot mode), L-Galaxies 2020 will output the properties listed in the Python-based "output structure" called LGalaxy_snapshots.py, which is in the /AuxCode/awk/output/python directory. The galaxytree equivalent of this, called LGalaxy_galtree.py, is also provided in the same directory. However, you are free to change which properties are actually outputted by L-Galaxies 2020. This is done as follows:

1. Open h_galaxy_output.h in the /code folder
2. In the GALAXY_OUTPUT structure, add/comment-out the property you wish to be outputted/not outputted
For example, to remove BulgeMassRings, either put it in a newly-defined #ifdef (see above) or directly comment it out:
• // float BulgeMassRings[RNUM];
3. Save and close h_galaxy_output.h
4. Open save.c in the /code folder
5. In the prepare_galaxy_for_output() function, add/comment-out the property you wish to be outputted/not outputted
For example, to remove BulgeMassRings, either put it in a newly-defined #ifdef (see above) or directly comment it out:
• // o->BulgeMassRings[ll] = g->BulgeMassRings[ll];
6. Save and close save.c
7. Open the output structure you are using (e.g. LGalaxy_snapshots.py, LGalaxy_galtree.py, or one you have created yourself)
8. In the LGalaxiesStruct structure, add/comment-out the property you wish to be outputted/not outputted
For example, to remove BulgeMassRings, set it to "False" in the properties_used dictionary (at the bottom of the .py file), or directly comment it out:
• # ('BulgeMassRings',numpy.float32,12),
The property in question will now be included/removed from the output file generated by L-Galaxies 2020.

Note: The majority of errors occurring when trying to read-in L-Galaxies output binaries into a python script come from a mis-match between the actual output and the output structure. Therefore, make sure you keep your output structure up-to-date with your code!

Although L-Galaxies 2020 can be used with any basic word processor and the command line, using an Interactive Development Environment (IDE) can make modifying, compiling, running, and debugging code significantly easier and more efficient. This can save a lot of time and energy in the long run. Therefore, we recommend an IDE (that is compatible with C makefile projects) is used when working with L-Galaxies. Below, we outline how to download, install, and synchronise the Java-based Eclipse IDE for L-Galaxies, which has already been extensively tried and tested with the code.

Install Cygwin:

1. If you haven't already, complete STEP 3 above to install GSL and the gcc compiler via Cygwin.

Install jdk:
Eclipse is a java-based IDE, so it needs the Java Development Kit (JDK) to run. You can check if JDK is already installed on your system by opening a cygwin terminal and running java -version. If this command returns information on a Java "Runtime Environment", you probably have a working version of JDK installed. If you don't have JDK, you can install the latest version as a private user as follows:

1. Go to: https://www.oracle.com/java/technologies/downloads/#jdk19-windows
2. Click the download link for the Java SE Development Kit 19.0.1 x64 Installer
3. Install to: C:\Program Files\Java\jdk-19\

Install Eclipse IDE:

1. Go to: https://www.eclipse.org/downloads/packages/installer
2. Click the download link for the Eclipse 2022-09 R x86_64 Installer for Windows
3. Once downloaded, execute the installer on your system
4. Select: Eclipse IDE for C/C++ Developers
5. Confirm: Java 17+ VM: C:\Program Files\Java\jdk-19 and Installation Folder: C:\Users\[username]\eclipse\cpp-2022-09
6. Accept the user agreement and click "launch"
7. Confirm the defauly workspace path and click "launch" again.

Clone L-Galaxies 2020 repository:

1. In the Eclipse IDE, click the "Open Perspective" button in the top right corner (symbol of a GUI interface with a plus sign)
2. Select "Git"
3. Click "Clone a Git Repository" (left)
4. Enter the L-Galaxies 2020 repository URI: https://github.com/LGalaxiesPublicRelease/LGalaxies2020_PublicRepository
5. Click "Next"
6. Make sure "master" is selected and click "Next"
7. Confirm the destination directory (this will become your git-synchronised project root directory).
8. Click "Finish"
9. Eclipse will now clone a local version of the L-Galaxies 2020 repository (progress bar in the bottom right corner)
10. Once cloned, right click the name of the project in the left-hand panel (LGalaxies2020_PublicRepository)
11. Click "Import projects..."
12. In the new window, click "Finish"
The L-Galaxies 2020 code is now ready to be used in the standard "C/C++ Perspective" in Eclipse

Define as a makefile project:

1. Click the "C/C++ Perspective" button in the top right corner (symbol of a GUI interface with a letter "C")
2. Click on the project name in the left-hand panel (LGalaxies2020_PublicRepository), so that it's highlighted
3. Press Ctrl+n on the keyboard
4. Select: "Convert to C/C++ project (Adds C/C++ Nature)" and click "Next"
5. Select: "C project" (below the heading called "Convert to C or C++")
6. Select: "Makefile project", and the "Cygwin GCC" toolchain
7. Click "Finish"

Set-up a run configuration:

1. In the "C/C++ perspective", click the project name in the left-hand panel (LGalaxies2020_PublicRepository), so that it's highlighted
2. From the top menu bar, select "Run" > "Run configurations..."
3. In the new window, click the "New Launch configuration" button (symbol of a blank page with a plus sign)
4. Set "Name" in the right hand panel to: "LGalaxies2020_PublicRepository" (i.e. delete " Default")
5. Set "C/C++ Application" to: "L-Galaxies.exe"
6. Click the "(x) = Arguments" tab
7. Under "Program arguments", add the local path to your preferred input file (e.g. ./input/input_MR_W1_PLANCK_LGals2020_DM.par)
8. Click "Apply", then click "Close"

Add an output folder:

1. In the "C/C++ perspective", right-click the project name in the left-hand panel (LGalaxies2020_PublicRepository)
2. Select "New" > "Folder"
3. In the new window, set Folder name as "output"
4. Click "Finish"

Download treefiles and specphot tables:

1. If you haven't already, complete STEP 2 above for this cloned L-Galaxies 2020 repository

Check compiler configuration:

1. Complete STEP 4 above to check the gcc compiler is configured correctly for L-Galaxies 2020 on your system. For example, you may need to set the SYSTYPE to "cygwin" in My_Makefile_compilers.

Compile and run in Eclipse:

1. In the "C/C++ perspective", click the project name in the left-hand panel (LGalaxies2020_PublicRepository), so that it's highlighted
2. To compile: Click the "Build" button in the top left corner (symbol of a hammer)
3. To run: Click the "Run" button in the top left corner (symbol of a green "play" sign)