diff --git a/Makefile b/Makefile index e62840b..99a8b3b 100644 --- a/Makefile +++ b/Makefile @@ -5,15 +5,17 @@ # Project and case definition PROJECT = Theoretical CASE = Theoretical -RUNFILE = runtracmass +RUNFILE = runtracmass ARCH = NETCDFLIBS = none #================================================================ # Possible architectures: # tetralith (Swedish HPC with intel) +# conda (gfortran compiler in conda virtual environment) # Possible netCDF settings: +# conda (set by nf-config in conda virtual environment) # automatic (set by nc-config) # automatic-44 (set by nf-config, for netCDF version >4.4) # none (no netCDF library) @@ -49,7 +51,7 @@ else ifeq ($(NETCDFLIBS),automatic) LIB_DIR = $(shell nc-config --flibs) INC_DIR = -I$(shell nc-config --includedir) -else ifeq ($(NETCDFLIBS),automatic-44) +else ifeq ($(NETCDFLIBS),$(filter $(NETCDFLIBS),conda automatic-44)) LIB_DIR = $(shell nf-config --flibs) INC_DIR = $(shell nf-config --cflags) @@ -66,6 +68,10 @@ ifeq ($(ARCH),tetralith) FC = ifort FF = -g -O3 -traceback -pg +else ifeq ($(ARCH),conda) +FC = gfortran +FF = -g -O3 -fbacktrace -fbounds-check -Wall -Wno-maybe-uninitialized -Wno-unused-dummy-argument -ftree-vectorize -funroll-loops -ffast-math + else FC = gfortran FF = -g -O3 -fbacktrace -fbounds-check -Wall -Wno-maybe-uninitialized -Wno-unused-dummy-argument diff --git a/README.md b/README.md index ae7a21a..229fbdd 100644 --- a/README.md +++ b/README.md @@ -10,90 +10,137 @@ The code is written in FORTRAN 90 with modules and runs on UNIX platforms such a **TRACMASS** has been set up to run with velocities integrated with models such as NEMO or IFS-ECMWF, of satellite datasets such as AVISO. -For more information check our website: https://www.tracmass.org/. +For more information check our website: **https://www.tracmass.org/**. Documentation ============= -You can find documentation about TRACMASS in - -https://www.tracmass.org/docs +You can find documentation about TRACMASS [**here**](https://www.tracmass.org/docs) Quickstart ========== -1. Download the code +### 1. Download TRACMASS ```bash git clone https://github.com/TRACMASS/Tracmass.git ``` -2. Enter the TRACMASS directory +### 2. Enter the TRACMASS directory ```bash cd Tracmass ``` -3. Modify the *Makefile* to fit your system. You will need to set ARCH, which is the name of your system, i.e. tetralith. You will also need to configure how **TRACMASS** should find the netCDF libraries, if at all. For most systems, we recommend the option **automatic-44**. +### 3. Modify the *Makefile* to fit your system. -4. Then you can run the make command +You will need to set `ARCH` - name of your system, (i.e. tetralith) - which is used to set the Fortran compiler and flags. + +You also need to configure how **TRACMASS** should find the netCDF libraries, if at all, using `NETCDFLIBS`. -```bash -make -``` +For most HPC systems, we recommend setting netCDF libraries using either the `NETCDFLIBS = automatic-44` option for netCDF version >4.4 or `NETCDFLIBS = automatic` otherwise. -Running a first test case -------------------------- +--- +#### **3.1 Using Conda:** + +The simplest way to get started with **TRACMASS** on a local machine or HPC system is to use a conda virtual environment. + +To do this: -We recommend testing that **TRACMASS** was properly compiled by letting PROJECT and CASE be **"Theoretical"** in the *Makefile* (which is the default). In this case, TRACMASS will use a simple oscillating velocity field to trace trajectories. +* Create a new virtual environment using [**miniforge**](https://github.com/conda-forge/miniforge) - a minimal installer for **Conda** and **Mamba**: + ```bash + conda create -n env_tracmass + ``` -1. Make sure in *Makefile* both PROJECT and CASE are set to Theoretical. +* Next, install the **gfortran** and **netcdf-fortran** libraries required by **TRACMASS** from the conda-forge open-source package manager. + ```bash + conda activate env_tracmass -2. Recompile the code + conda install gfortran netcdf-fortran + ``` + +* Verify **gfortran** and **netCDF** libraries are available. + ```bash + which gfortran + + nf-config --all + ``` + +* Update the *Makefile* `ARCH` and `NETCDFLIBS` options. + ```bash + # Project and case definition + ... + ARCH = conda + NETCDFLIBS = conda + #============================= + ``` + +--- + +### 4. Compile TRACMASS ```bash -make clean make ``` -3. Run the code by typing +Running the First Test Case +--------------------------- -```bash -./runtracmass -``` +We recommend testing that **TRACMASS** was properly compiled by letting `PROJECT` and `CASE` be **"Theoretical"** in the *Makefile* (which is the default). -Download test data ------------------- +In this case, **TRACMASS** will use a simple oscillating velocity field to trace trajectories. -You can find some input data for testing the code on +1. Make sure in *Makefile* both `PROJECT` and `CASE` are set to `Theoretical`. -```bash -https://stockholmuniversity.box.com/s/pyc29hjumxuvf0nf84ym5zs0vrnqbswr -``` + ```bash + # Project and case definition + PROJECT = Theoretical + CASE = Theoretical + ... + ``` + +2. Recompile **TRACMASS** + + ```bash + make clean + make + ``` + +3. Run **TRACMASS** -This test data includes data from NEMO, IFS and AVISO. -Before doing any analysis we recommend to download some of the test data and make sure TRACMASS is working properly. + ```bash + ./runtracmass + ``` -In order to set up TRACMASS to run trajectories on e.g. NEMO data, you will need to change PROJECT and CASE to NEMO, and then re-compile the code. +Download Example Data +--------------------- + +You can find example input data for testing the code here: **https://stockholmuniversity.box.com/s/pyc29hjumxuvf0nf84ym5zs0vrnqbswr** + +This includes data from NEMO, IFS and AVISO. Before doing any analysis we recommend to download some of the test data and make sure **TRACMASS** is working properly. + +For example, in order to set up **TRACMASS** to run trajectories using NEMO model output data, you will need to change `PROJECT` and `CASE` to `NEMO`, and then re-compile the code. ```bash make clean make + ./runtracmass ``` -Run your analysis ------------------ +Perform Your Own Analysis +------------------------- + +If you wish to run another case or a very specific case of the above models, you will need create your own project in the `projects` directory. -If you wish to run another case or a very specific case of the above models, you may create your own project in the projects directory. -To run with e.g. your own IFS data, you will need to modify the projects/IFS/namelist_IFS.in namelist to suit your needs. +For example, to run with your own IFS data, you will need to modify the `namelist_IFS.in` namelist in the `projects/IFS/` directory to suit your needs. -Previous versions of TRACMASS +Previous Versions of TRACMASS ============================= Previous versions of **TRACMASS** are stored in the following repository: -https://github.com/TRACMASS/Tracmass_previous.git +**https://github.com/TRACMASS/Tracmass_previous.git** The following features from older versions are not available yet in this version: