From d0b9d6bb02260d6286e5b0fdc9bbcca0378c449c Mon Sep 17 00:00:00 2001 From: Sam Harrison Date: Tue, 19 Dec 2023 10:16:49 +0000 Subject: [PATCH] Updating docs --- build.rsp | 4 ++++ docs/getting-started/building-the-model.md | 20 ++++++++++++++++++-- docs/getting-started/running-the-model.md | 15 ++++++++++++--- docs/intro.md | 13 +++++++++++-- 4 files changed, 45 insertions(+), 7 deletions(-) create mode 100644 build.rsp diff --git a/build.rsp b/build.rsp new file mode 100644 index 0000000..547a315 --- /dev/null +++ b/build.rsp @@ -0,0 +1,4 @@ +# Fpm options to build the debug version of the model +options build +options --profile debug +options --flag "-Og -pg -Wall -fallow-argument-mismatch" diff --git a/docs/getting-started/building-the-model.md b/docs/getting-started/building-the-model.md index 96f3e83..f6221b0 100644 --- a/docs/getting-started/building-the-model.md +++ b/docs/getting-started/building-the-model.md @@ -25,9 +25,25 @@ If you forget the `--recurse-submodule` flag, then run the following from the re $ git submodule update --init --recursive ``` +## Using fpm (Fortran Package Manager) + +The easiest way to build the model is use [fpm](https://fpm.fortran-lang.org/) (Fortran Package Manger). You can install this easily using Conda (`conda install -c conda-forge fpm`). To build the model without installing: + +```sh +$ fpm @build +``` + +The model binary will be placed in a subdirectory of the `build` folder. The `fpm @run` command can be used to run this executable (see [](./running-the-model)). Alternatively, you can install the model: + +```sh +$ fpm @install +``` + +Optionally, you can provide an install directory using `--prefix `, otherwise the model will install to a default location for your system (e.g. `/home//.local` on Linux) + ## Using CMake -The easiest way to build the model is using CMake: +The model can also be built using CMake: ```sh $ mkdir build && cd build @@ -59,4 +75,4 @@ The model will be built into the `build` directory by default (a custom director We are also working towards supporting the [Fortran Package Manager](https://fpm.fortran-lang.org/) (FPM), but are not quite there yet. See the [fpm.toml](https://github.com/NERC-CEH/nanofase/blob/develop/fpm.toml) file for the work-in-progress FPM manifest file. -The model can also be compiled using Visual Studio with the Intel Fortran integration. See [](../developers/vs-ifort-setup.md) for a guide on compiling using Visual Studio 2017. \ No newline at end of file +The model can also be compiled using Visual Studio with the Intel Fortran integration. See [](../developers/vs-ifort-setup.md) for a guide on compiling using Visual Studio 2017. diff --git a/docs/getting-started/running-the-model.md b/docs/getting-started/running-the-model.md index 47cdf42..bf16937 100644 --- a/docs/getting-started/running-the-model.md +++ b/docs/getting-started/running-the-model.md @@ -4,11 +4,20 @@ ## Running -The model requires a config file to run. Examples are given in the [config.example](https://github.com/NERC-CEH/nanofase/tree/develop/config.example) directory. The examples are commented and should be relatively self-explanatory. Copy one of these to a new file and edit as you wish. Make sure the directories you specify for output data and logs exist, otherwise the model will fail. Then pass this config file as the first argument when calling the model executable. For example: +The model requires a config file to run. Examples are given in the [config.example](https://github.com/NERC-CEH/nanofase/tree/develop/config.example) directory. The examples are commented and should be relatively self-explanatory. Copy one of these to a new file and edit as you wish. Make sure the directories you specify for output data and logs exist, otherwise the model will fail. Then pass this config file as the first argument when calling the model executable. For example, if you have installed the model to somewhere on your path: ```shell $ mkdir config && cp config.example/config.example.nml config/my_config.nml -$ build/nanofase config/my_config.nml +$ nanofase config/my_config.nml +``` + +Or if you wish to run via fpm without installing: + +```shell +# Debug version +$ fpm @run -- config/my_config.nml +# Release version with optimisations +$ fpm @release -- config/my_config.nml ``` ### Input data @@ -27,4 +36,4 @@ The model allows for multiple simulations to be chained together into batch runs ## Example workflows -A few example workflows are provided in [](../users/example-workflows.md). \ No newline at end of file +A few example workflows are provided in [](../users/example-workflows.md). diff --git a/docs/intro.md b/docs/intro.md index 7431243..deaed72 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -8,7 +8,7 @@ The NanoFASE model is a multimedia spatiotemporal environmental fate and exposur ## Quickstart guide -The easiest way to install the project is to use the [Fortran Package Manager](https://fpm.fortran-lang.org/en/install/index.html#install), which can be installed using Conda (`conda install -c conda-forge fpm`). The model also requires a recent version of GFortran, NetCDF Fortran and Git installed (see [](./getting-started/building-the-model.md)). +The easiest way to install the model is to use the [Fortran Package Manager](https://fpm.fortran-lang.org/en/install/index.html#install), which can be installed using Conda (`conda install -c conda-forge fpm`). The model also requires a recent version of GFortran, NetCDF Fortran and Git installed (see [](./getting-started/building-the-model.md)). Clone the code (make sure to `--recurse-submodules`) and use *fpm* to install: @@ -27,6 +27,15 @@ $ mkdir log output $ nanofase config.example/test-scenario.nml ``` +Or you can use fpm to run the model, without needing to install it first (i.e. omitting the `fpm @install` step above): + +```shell +# Debug version +$ fpm @run -- config.example/test-scenario.nml +# Release version with optimisations turned on +$ fpm @release -- config.example/test-scenario.nml +``` + Take a look at the NetCDF output file using your software of choice. For example, using Python's `xarray` to plot the pristine NM concentration in rivers at the end of the model run (2015-01-11): ```python @@ -45,4 +54,4 @@ Next steps: ## Acknowledgements -This model has received funding from the European Union's Horizon 2020 research and innovation programme under grant agreement numbers 646002 (NanoFASE), 814572 (NanoSolveIT), 862419 (SAbyNA), 862444 (ASINA) and 731032 (NanoCommons). \ No newline at end of file +This model has received funding from the European Union's Horizon 2020 research and innovation programme under grant agreement numbers 646002 (NanoFASE), 814572 (NanoSolveIT), 862419 (SAbyNA), 862444 (ASINA) and 731032 (NanoCommons).