search

PrincetonUniversity / tristan-mp-v2

Tristan-MP v2 [public]
https://princetonuniversity.github.io/tristan-v2/
BSD 3-Clause "New" or "Revised" License
12 stars 2 forks source link

readme

Tristan v2.8

DOI

For detailed tutorials and code description please visit our wiki. If you are a new user testing the code on a new computer cluster, please consider contributing to this chapter about cluster-specific configuration to make the life easier for future generations.

Getting Started

Prerequisites

On clusters typically all you need to do is to load the specific modules see here.

If you are, however, running on a local machine make sure to install the following prerequisites (assuming non-Intel compiler and apt package manager):

# gcc + openmpi
sudo apt install build-essential libopenmpi-dev
# hdf5
sudo apt libhdf5-openmpi-dev hdf5-tools

Also make sure you have a working python3 installation to be able to configure the code.

Usage

configure.py + GNU Make

# to view all configuration options
python3 configure.py --help
# to configure the code (example)
python3 configure.py -mpi08 -hdf5 --user=user_2d_rec -2d
# compile and link (-j compiles in parallel which is much faster)
make all -j
# executable will be in the `bin/` directory

Cmake

Since v2.8 we also support cmake for the code configuration. 

# to configure the code (example)
cmake -B build -D mpi08=ON -D hdf5=ON -D user=user_2d_rec -D dim=2
# compile
cmake --build build -j
# executable will be in the `build/src/` directory (*.xc extension)

Running:

# run the code (on clusters need to do `srun`, or `irun` etc. depending on the cluster)
mpirun -np <NCORES> ./<EXECUTABLE> -input <INPUTFILE> -output <OUTPUTDIR>

CMake (experimental support)

# preconfigure the code using
cmake -B build -D user=<USERFILE> -D dim=3 ...
# compile
cmake --build build -j $(nproc)

Docker

Another way to avoid the tedium of installing libraries (especially for local development) is to use Docker containers. This approach allows to quickly create an isolated linux environment with all the necessary packages already preinstalled (similar to a VM, but much lighter). The best thing is that VSCode can natively attach to a running container, and all the development can be done there (make sure to install the appropriate extension).

To get started with this approach, make sure to install the Docker (as well as the Docker-compose) then simply follow these steps.

# from tristan root diretory
cd docker
# launch the container in the background (first-time run might take a few mins)
docker-compose up -d
# if you are attempting to also force rebuild the container, use the `--build` flag
docker-compose up -d --build
# ensure the container is running
docker ps

Then you can attach to the container via VSCode, or if you prefer the terminal, simply attach to the running container by doing:

docker exec -it trv2 zsh
# then the code will be in the `/home/$USER/tristan-v2` directory
cd /home/$USER/tristan-v2

To stop the container run docker-compose stop. To stop and delete the container simply run docker-compose down from the same docker/ directory.

Each container has in principle its own isolated filesystem, aside from the shared /root/tristan-v2 directory. Any changes to the rest of the container's filesystem are discarded when the container is deleted (either via docker-compose down or directly docker rm <CONTAINER>).

For developers/users

Branching Policy

To prevent v2 from growing to become the Lovecraftian monster it once was we highly encourage both users and developers to follow the guidelines on branching policies.

The dev/main branch is the most up-to-date tested version of the code, and it will be merged to master as soon as all the new features are documented.

Development

Since v2.4 code formatting policy is employed. To follow the proper formatting automatically we use the fprettify tool. To install fprettify in the local directory (via pip) one can use the dev-requirements.txt file, by running the following: 

# create a local pip environment
python3 -m virtualenv venv
# activate it
source venv/bin/activate
# install required modules
pip install -r dev-requirements.txt

After that one can either use the tool in a stand-alone manner:

./venv/bin/fprettify -i 2 -w 4 --whitespace-assignment true --enable-decl --whitespace-decl true --whitespace-relational true --whitespace-logical true --whitespace-plusminus true --whitespace-multdiv true --whitespace-print true --whitespace-type true --whitespace-intrinsics true --enable-replacements -l 1000 [FILENAME.F90]

or in the VSCode environment (see the extension list in the .vscode/settings.json of the current repo).

Contributors (alphabetical order)

Board of trustees

Publications

@TODO

Latest Releases

We employ semantic versioning for this code. Given a version number v<MAJOR>.<MINOR>.<PATCH>r<CANDIDATE>, increment the: