AetherModel / Aether

This is the home of the Aether model of the thermosphere and ionosphere
GNU General Public License v3.0
19 stars 29 forks source link
ionosphere modeling simulations simulations-physics space thermosphere

Aether

This is the home of the Aether model of the thermosphere and ionosphere.

The Aether model has been developed using gnu c++ (versions 9, 10, 11). If you are using this, hopefully it will just work out of the box. We have been doing development of Aether on Mac OSX, and in Ubuntu Linux. We have also used the Windows Subsystem for Linux, Ubuntu distribution, which works similarly to the native Linux distribution.

If you are a student and don't know how to work with a large code base (i.e., multiple source codes in multiple directories), you may consider starting with the doc/student.md file.

Dependencies:

On Mac, installing some of the dependencies can be awkward, depending on which c++ compiler you are using. Since there is one that essentially comes with Mac OSX, called clang, the default compiler is often this. Much of the other software is not built with this, so you need to switch compilers, which can be challenging.

While the development team has tried to remove as many of the dependencies as possible to reduce this issues, it is still a good idea to try to get a different compiler to work. If you want to use netCDF files or the fortran compiled options (like MSIS), you will probably have to do this.

  1. Install gcc. This comes install by default on Ubuntu. For MacOS, this can be installed using macports:

    sudo port install gcc11

    (At this moment, gcc11 is the latest version, there may be a more up-to-date version available now.)

  2. Aether uses CMake instead of make. If you don't have it installed, you need it.

For MacOS, this can be installed using macports

sudo port install cmake

Or using homebrew:

sudo brew install cmake

The development team has mostly used macports and not homebrew.

For Ubuntu/Debian Linux:

sudo apt install cmake

This can be done on redhat using yum also.

  1. Aether uses the nlohman json package for reading and writing json files.

On Ubuntu:

sudo apt-get install -y nlohmann-json3-dev

On Mac:

sudo port install nlohmann-json 
  1. The armadillo headers need to be installed. Simplistically, Armadillo is a system that allows matrix math to be done in C++ easily. We mostly use it for doing math with matrices (like multiplication, addition, etc.), but it is much more powerful than this. You will notice that there are not many 3D loops in Aether, which is due to Armadillo. To make this all fast, it is best to install the lapack abd blas libraries too.

On Ubuntu:

sudo apt-get install liblapack-dev
sudo apt-get install libblas-dev
sudo apt-get install libboost-dev
sudo apt-get install libarmadillo-dev
sudo apt-get install openmpi-bin libopenmpi-dev

On Mac:

sudo port install lapack
sudo port install OpenBLAS
sudo port install boost
sudo port install armadillo
sudo port install openmpi-bin libopenmpi-dev
  1. We have removed the strict dependency for netcdf, but a lot of codes used netCDF, so it doesn't hurt to try to install the libraries. Aether uses the netcdf library (netcdf-cxx4). As above, netCDF can be installed using a package manager.

On Mac, if you want the clang compiled version of netcdf, then:

sudo port install netcdf-cxx4

If you want the gcc version of netcdf, then:

sudo port install netcdf-cxx4 +gcc10

On Ubuntu, gcc is the default compiler, it seems like you can probably just do:

sudo apt-get install libnetcdf-dev
sudo apt install libnetcdf-c++4-dev

Quick Start:

These are unix commands, assuming that you have access to a unix/linux terminal. This has been tested on a MacBook Pro and Ubuntu. (This is assuming that you are installing the root version of Aether and not a forked version. If you are using a forked version, replace the "AetherModel" with the appropriate location of the fork.)

git clone https://github.com/AetherModel/Aether
cd Aether
git checkout develop

To compile Aether:

mkdir build
cd build
cmake ..
make [-j4]

The -j4 is optional and uses 4 processors, but you could use 2, 4, 8, or whatever.

To compile Aether with NetCDF:

mkdir build
cd build
cmake -DUSE_NETCDF=Y ..
make [-j4] (the -j4 uses 4 processors)

To compile Aether with FORTRAN codes:

mkdir build
cd build
cmake -DUSE_FORTRAN=Y ..
make [-j4] (the -j4 uses 4 processors)

To compile Aether with double precision:

mkdir build
cd build
cmake -DUSE_DOUBLE_PRECISION=Y ..
make [-j4] (the -j4 uses 4 processors)

Once you have compiled you can install Aether with an example run directory structure like this:

cd ..
cp -R share/run ./run.test
cd run.test
./aether

There are essentially two input files that specify the settings in the code. When you are in a run directory, they are:

  1. UA/inputs/defaults.json. These set the default inputs for the run and should not be modified at all. You can look at these and copy the settings that you want to change to this file:

  2. aether.json. This file can and should be modified to direct the code to run the way that you would like. You can copy settings from the default.json file and then modify them here. This will be covered in the reference manual, once we have written one.

You can check to make sure that these are valid json files (not checking the content, though) with:

cd run.test
python -m json.tool aether.json
python -m json.tool UA/inputs/defaults.json

At this time, there is no checker to see if all of the settings in each of the inputs files are actually valid and Aether understands them.

Output files are in UA/output.

We are working on aetherpy to make plots.

Compare png files to tests/outputs_pngs/*.png to see if they are similar.

Code Manual:

To create the code documentation manual, download Doxygen for your operating system and run:

cd doc
doxygen Doxyfile