Adding input data documentation

conda.recipe/meta.yaml

@@ -1,6 +1,6 @@
 package:
   name: nanofase
-  version: {{ GIT_DESCRIBE_TAG }}
+  version: 0.0.4
 
 source:
   path: ..
@@ -22,4 +22,10 @@ requirements:
 
 about:
   home: https://nerc-ceh.github.io/nanofase
-  license: BSD 3 Clause
+  license: BSD 3 Clause
+  summary: Nanomaterial exposure in the environment
+  description: |
+    NanoFASE is a multimedia spatiotemporal model of nanomaterial
+    fate and exposure in the environment.
+  dev_url: https://github.com/nerc-ceh/nanofase
+  doc_url: https://nerc-ceh.github.io/nanofase

doc/output.md

@@ -1,6 +1,6 @@
-# Data output
+# Output data
 
-Data output is handled by the [`DataOutput`](../src/Data/DataOutputModule.f90) class and configured in the [model config file](../config/config.example.nml). Output is to a series of text files:
+Data output is handled by the [`DataOutput`](../src/Data/DataOutputModule.f90) class and configured in the [model config file](https://github.com/NERC-CEH/nanofase/blob/develop/config.example/config.example.nml). Output is to a series of text files:
 
 - `summary.md`: A plain-text summary of the model simulation, including compartmental mean PECs. These means are simply a summary of what is output in the following CSV files.
 - `output_water.csv`: Output data for every waterbody.
@@ -11,7 +11,7 @@ Data output is handled by the [`DataOutput`](../src/Data/DataOutputModule.f90) c
 
 ## Configuration
 
-The `&output` group in the [model config file](../config.example/config.example.nml) is responsible for configuring data output. The following options are available:
+The `&output` group in the [model config file](https://github.com/NERC-CEH/nanofase/blob/develop/config.example/config.example.nml) is responsible for configuring data output. The following options are available:
 
 - `write_metadata_as_comment`: Should metadata (largely column descriptions) be writen to the header of each CSV file as `#` delimited comments? Top tip: If you turn metadata on and are using Pandas to read the data, then make sure to use the `comment` argument when reading the CSV: `df = pd.read_csv('output_water.csv', comment='#')`. *Defaults to true.* 
 - `include_waterbody_breakdown`: For surface waters, should data for each waterbody be output, or should it be aggregated to grid cell level? *Defaults to true.*

docs/_config.yml

@@ -3,7 +3,7 @@
 
 title: NanoFASE
 author: Sam Harrison
-copyright: "2022"
+copyright: "2024"
 logo: logo.png
 
 # Force re-execution of notebooks on each build.

docs/_toc.yml

@@ -11,8 +11,13 @@ parts:
     - file: getting-started/test-scenario
   - caption: Users
     chapters:
-    - file: users/example-workflows
+    - file: users/input-data
+      sections:
+        - file: users/nanofase-data
+        - file: users/netcdf-namelist-input
+        - file: users/parameter-reference
     - file: users/output
+    - file: users/example-workflows
     - file: users/temporal-period
     - file: users/batch
     - file: users/checkpointing
@@ -26,4 +31,7 @@ parts:
   - caption: Developers
     chapters:
     - file: developers/conventions
-    - file: developers/io-units
+    - file: developers/io-units
+  - caption: Reference
+    chapters:
+    - file: references

docs/references.md

@@ -0,0 +1,5 @@
+# References
+
+```{bibliography}
+:style: plain
+```

docs/theory/conceptual-structure.md

@@ -20,9 +20,9 @@ classDiagram
     BedSedimentLayer --o "1" Reactor
 ```
 
-Here, `Environment` represents the geographical area that we wish to model (e.g. a river catchment), which is divided into a number of `GridCell`s to give spatial resolution. Each `GridCell` can one or more `SoilProfile`s, which are split vertically into one or more `SoilLayer`s to give vertical resolution down the soil profile. `GridCell`s can also contain up to eight `WaterBody` objects (see [](surface-water-network)), each of which is an abstraction of a specific type of waterbody, such a `RiverReach` or `EstuaryReach`. Unlike `SoilProfile`s, `WaterBody` objects are linked across `GridCell`s to model the flow of water, sediment and contaminants around the environment. Each `WaterBody` contains a `BedSediment`, which is further split into a vertical distribution of `BedSedimentLayer`s. The final object is the `Reactor`, which is responsible for modelling the physical and chemical state of the contaminant being modelled.
+Here, `Environment` represents the geographical area that we wish to model (e.g. a river catchment), which is divided into a number of `GridCell`s to give spatial resolution. Each `GridCell` can one or more `SoilProfile`s, which are split vertically into one or more `SoilLayer`s to give vertical resolution down the soil profile. `GridCell`s can also contain up to eight `WaterBody` objects (see [](conceptual-structure:surface-water-network)), each of which is an abstraction of a specific type of waterbody, such a `RiverReach` or `EstuaryReach`. Unlike `SoilProfile`s, `WaterBody` objects are linked across `GridCell`s to model the flow of water, sediment and contaminants around the environment. Each `WaterBody` contains a `BedSediment`, which is further split into a vertical distribution of `BedSedimentLayer`s. The final object is the `Reactor`, which is responsible for modelling the physical and chemical state of the contaminant being modelled.
 
-(surface-water-network)=
+(conceptual-structure:surface-water-network)=
 ## Surface water network
 
 *To be completed...*

docs/users/input-data.md

@@ -0,0 +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.
+* 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