diff --git a/README.md b/README.md index 3ddbefe..81c57b6 100644 --- a/README.md +++ b/README.md @@ -8,14 +8,14 @@ Multimedia spatiotemporal environmental fate and exposure model for engineered n Simply clone this repo, making sure to specify `--recurse-submodules` to pull in code for the submodules in the `vendor/` directory: -```shell +```console $ git clone https://github.com/nerc-ceh/nanofase.git --recurse-submodules $ cd nanofase ``` If you forget the `--recurse-submodule` flag, then run the following from the repo directory: -```shell +```console $ git submodule update --init --recursive ``` @@ -27,7 +27,7 @@ We recommend compiling using GFortran version 10 or higher. The only dependency An example makefile ([Makefile.example](./Makefile.example)) is provided. If you already have NetCDF installed, then compiling the model is as simple as making the `bin` directory to place your exectuble in, then running `make`: -```shell +```console $ cp Makefile.example Makefile $ mkdir bin $ make @@ -35,7 +35,7 @@ $ make The [example makefile](./Makefile.example) provides targets for debug, release and "fast" compilation. The main make target builds the debug version, whilst the `release` and `fast` targets build optimised release versions (`release` uses `-O3`, `fast` uses `-Ofast -march=native -mtune=native`). Run times can be significantly improved using the `release` and `fast` targets, and so unless you need detailed debugging or profiling, then it is recommended to use one of these. -```shell +```console # Build the debug version $ make # OR, build the release version @@ -48,7 +48,7 @@ $ make fast The model can also be built using `cmake`, using the [CMakeLists.txt](./CMakeLists.txt) file. Use the standard `cmake` procedure to compile the model: -```shell +```console $ mkdir build && cd build $ cmake .. $ make @@ -62,7 +62,7 @@ Note that, whilst `cmake` can be used to compile the model using the `ifort` or The only dependency outside of the `vendor` directory (which are compiled from source when the model is compiled, so don't worry about these) is the [NetCDF Fortran](https://www.unidata.ucar.edu/software/netcdf/docs/building_netcdf_fortran.html) library, which must already be installed on your system. NetCDF4 is available on most default application repositories, such as those for Ubuntu and Red Hat, and this is the easiest way to install. For example, on Ubuntu: -```shell +```console $ sudo apt-get install libnetcdf-dev $ sudo apt-get install libnetcdff-dev ``` @@ -75,7 +75,7 @@ If you're on Windows, it is highly recommended to use Cygwin or a Linux containe The model requires a config file to run. An example is placed at [config.example/config.example.nml](./config.example/config.example.nml). The example is commented and should be relatively self-explanatory. Copy this 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 compiled the model to `./bin/main`: -```shell +```console $ ./bin/main /path/to/config/file.nml ``` diff --git a/doc/example-workflows.md b/doc/example-workflows.md index 10f1701..5cdfb4c 100644 --- a/doc/example-workflows.md +++ b/doc/example-workflows.md @@ -37,7 +37,7 @@ emissions_areal_soil_pristine: Save this to `vendor/nanofase-data/config.edit.yaml`. Now we can run the data compiler, which is provided as a submodule to this repo: -```shell +```console $ vendor/nanofase-data/nanofase_data.py edit vendor/nanofase-data/config.edit.yaml ``` @@ -63,7 +63,7 @@ output_path = "data/output/" Now you're ready to run the model with this updated config file: -```shell +```console $ make run CONFIG_PATH=config/ CONFIG_FILE=config.nml ``` diff --git a/doc/temporal-period.md b/doc/temporal-period.md index 40eae2b..4556c00 100644 --- a/doc/temporal-period.md +++ b/doc/temporal-period.md @@ -19,14 +19,14 @@ The good news is that there are a variety of very easy methods to slice a NetCDF If you have NetCDF installed, you almost certainly have the NetCDF command line utilities installed, including the NetCDF Kitchen Sink `ncks`. Slicing a time dimension is as easy as: -```shell -ncks -d t,start_time,end_time in.nc out.nc +```console +$ ncks -d t,start_time,end_time in.nc out.nc ``` where `start_time` and `end_time` are zero-indexed integers (use the flag `-F` if you want one-indexed). So, using our example, to slice June from the [example Thames 2015 data](../data.example/thames_tio2_2015.nc), we slice between 152 (1 June) and 181 (30 June): -```shell -ncks -d t,152,181 thames_tio2_2015.nc thames_tio2_june2015.nc +```console +$ ncks -d t,152,181 thames_tio2_2015.nc thames_tio2_june2015.nc ``` ### Slicing a NetCDF file in Python using `xarray` diff --git a/docs/_config.yml b/docs/_config.yml index 59d7eed..2d46675 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -43,6 +43,7 @@ parse: sphinx: config: mathjax_path: https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js + copybutton_exclude: '.linenos, .gp' extra_extensions: - 'sphinx.ext.autodoc' - 'sphinx.ext.napoleon' diff --git a/docs/getting-started/building-the-model.md b/docs/getting-started/building-the-model.md index 341b522..dbc879d 100644 --- a/docs/getting-started/building-the-model.md +++ b/docs/getting-started/building-the-model.md @@ -15,14 +15,14 @@ If your system has multiple versions of GFortran installed, make sure that the N First, get a copy of the code by cloning the repo, making sure to specify `--recurse-submodules` to pull in code for the submodules in the `vendor/` directory: -```shell +```console $ git clone https://github.com/nerc-ceh/nanofase.git --recurse-submodules $ cd nanofase ``` If you forget the `--recurse-submodule` flag, then run the following from the repo directory: -```shell +```console $ git submodule update --init --recursive ``` diff --git a/docs/getting-started/running-the-model.md b/docs/getting-started/running-the-model.md index bf16937..5eeeb4a 100644 --- a/docs/getting-started/running-the-model.md +++ b/docs/getting-started/running-the-model.md @@ -6,14 +6,14 @@ 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 +```console $ mkdir config && cp config.example/config.example.nml config/my_config.nml $ nanofase config/my_config.nml ``` Or if you wish to run via fpm without installing: -```shell +```console # Debug version $ fpm @run -- config/my_config.nml # Release version with optimisations diff --git a/docs/intro.md b/docs/intro.md index 16f736f..81ac20e 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -12,7 +12,7 @@ The easiest way to install the model is to use the [Fortran Package Manager](htt Clone the code (make sure to `--recurse-submodules`) and use *fpm* to install: -```shell +```console $ git clone git@github.com:NERC-CEH/nanofase.git --recurse-submodules $ cd nanofase $ fpm @install @@ -26,14 +26,14 @@ Use the `--prefix ` flag to install the model into a d Test the model with the [test scenario](getting-started/test-scenario.md). Presuming the install directory is on your `$PATH`: -```shell +```console $ mkdir log output $ nanofase config.example/test-scenario.example.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 +```console # Debug version $ fpm @run -- config.example/test-scenario.example.nml # Release version with optimisations turned on diff --git a/docs/users/input-data.md b/docs/users/input-data.md index 1d8b905..570669d 100644 --- a/docs/users/input-data.md +++ b/docs/users/input-data.md @@ -1,9 +1,9 @@ # Input data The model requires a NetCDF file of spatio(temporal) input data, and a Fortran namelist file for constants. The config file is responsible for telling the model where these input data are located (via the `&data` group). There are two options for generating these input data files: -* *Recommended*: Use the [NanoFASE data module](https://github.com/nerc-ceh/nanofase-data) - see [](nanofase-data). This is a Python script that compiles multiple spatio(temporal) input files into the main NetCDF file, at the same time as deriving secondary variables from these data, which are required by the model. +* *Recommended*: Use the [NanoFASE data module](https://github.com/nerc-ceh/nanofase-data) - see [](nanofase-data). This is a Python library that compiles multiple spatio(temporal) input files into the main NetCDF file, at the same time as deriving secondary variables from these data, which are required by the model. * Manually creating (or editing a copy of) the NetCDF and namelist files. This is not recommended for compiling new data (though can be useful for editing existing data) due to the requirement for a range of [secondary derived variables](netcdf-namelist-input:secondary-derived-variables) that would have to be calculated manually. If you wish to go down this route, see [](netcdf-namelist-input) for details of the variables required in the NetCDF and constants namelist file. The complete list of parameters required by the model is givin in [](parameter-reference). Example NetCDF and constants files are given in the [data.example](https://github.com/NERC-CEH/nanofase/tree/develop/data.example) directory. -% draw diagram of data input components \ No newline at end of file +% TODO draw diagram of data input components \ No newline at end of file diff --git a/docs/users/nanofase-data.md b/docs/users/nanofase-data.md index 45622c7..71e3459 100644 --- a/docs/users/nanofase-data.md +++ b/docs/users/nanofase-data.md @@ -1,24 +1,45 @@ # Compiling data with the NanoFASE data module -The *NanoFASE data module* (`nfdata`) is a Python library that is used to compile input data for the model. It is recommended to use this library over and above manually compiling the NetCDF and constants namelist file required by the model, as the data module scripts take care of deriving a variety of [secondary derived variables](netcdf-namelist-input:secondary-derived-variables), amongst other reasons. +The *NanoFASE data module* (`nfdata`) is a Python package that is used to compile input data for the model. It is recommended to use this package over and above manually compiling the NetCDF and constants namelist file required by the model, as the data module scripts take care of deriving a variety of [secondary derived variables](netcdf-namelist-input:secondary-derived-variables), amongst other reasons. -The library can be [found on GitHub](https://github.com/nerc-ceh/nfdata). +The package source code can be [found on GitHub](https://github.com/nerc-ceh/nfdata). ## Getting started -The easiest way to use the library is to [install it from PyPI](https://pypi.org/project/nfdata/). For example, using pip: +The package is available on [PyPI](https://pypi.org/project/nfdata/) or [Conda](https://anaconda.org/samharrison7/nfdata), and the easiest way to use the package is to install one of these using Pixi, Conda/Mamba or Pip: -```bash +`````{tab-set} +````{tab-item} Conda +```console +$ conda install -c samharrison7 nfdata +``` +```` +````{tab-item} Mamba +```console +$ mamba install -c samharrison7 nfdata +``` +```` +````{tab-item} Pip +```console $ pip install nfdata ``` - -```{note} -We are currently working on a Conda package for the library - watch this space! +```` +````{tab-item} Pixi (global) +```console +$ pixi global install -c samharrison7 nfdata +``` +```` +````{tab-item} Pixi (project) +```console +$ pixi project channel add samharrison7 +$ pixi add nfdata ``` +```` +````` ## Basic usage -Once installed, the library can be run via the command line using the `nfdata` command: +Once installed, the package can be run via the command line using the `nfdata` command: ``` $ nfdata --help @@ -41,7 +62,7 @@ options: Specifying the "create" option compiles a new NetCDF dataset and Fortran namelist constant file: -```shell script +```console $ nfdata create /path/to/config.create.yaml ``` @@ -53,7 +74,7 @@ The two files will be output to the paths specified in the config file. To edit an existing NetCDF dataset, specify the "edit" option: -```shell script +```console $ nfdata edit /path/to/config.edit.yaml ``` @@ -67,7 +88,7 @@ The Fortran namelist file cannot be edited using this method and you should inst To simply convert a constants YAML file to a Fortran namelist file, you can use the `constants` option: -```shell script +```console $ nfdata constants /path/to/constants.yaml -o /path/to/constants.nml ```