Merge pull request #60 from nichollsh/cond

Updates to condensation and file storage

.gitignore

@@ -21,8 +21,11 @@ docs/build
 *.par 
 *.xsc
 *.bin
-res/spectral_files/*/4096
-res/spectral_files/Reach/
+
+# Model data
+res/spectral_files/*
+res/stellar_spectra/*
+!res/*/_readme.txt
 
 # Output files 
 out/*

.vscode/settings.json

@@ -1,4 +1,5 @@
 {
     "julia.environmentPath": "${workspaceFolder}/",
     "editor.tabSize": 4,
+    "editor.rulers": [ 92 ],
 }

CITATION.cff

@@ -5,7 +5,7 @@ authors:
   given-names: "Harrison"
   orcid: "https://orcid.org/0000-0002-8368-4641"
 title: "AGNI"
-version: 0.5.3
+version: 0.6.0
 doi: 10.xx/xx.xx
-date-released: 2024-07-02
+date-released: 2024-07-17
 url: "https://github.com/nichollsh/AGNI"

Project.toml

@@ -1,7 +1,7 @@
 name = "AGNI"
 uuid = "ede838c1-9ec3-4ebe-8ae8-da4091b3f21c"
 authors = ["Harrison Nicholls <[email protected]>"]
-version = "0.5.3"
+version = "0.6.0"
 
 [deps]
 ArgParse = "c7e460c6-2fb9-53a9-8c5b-16f535851c63"

README.md

@@ -7,26 +7,26 @@ The model is distributed under a proprietary license. Only once it has been publ
 
 Consult the [AGNI documentation](https://nichollsh.github.io/AGNI/) for information about the model. 
 
-Contact: `harrison.nicholls [a] physics.ox.ac.uk`   
+Contact: `harrison[dot]nicholls[at]physics.ox.ac.uk`   
 
 GitHub: https://github.com/nichollsh/AGNI    
 
 
 ## Installation and usage
 See the Getting Started page in the [documentation](https://nichollsh.github.io/AGNI/) for information on installing and using the model.
-
 
 ## Repository structure 
-* `agni.jl`         - AGNI executable
+* `agni.jl`         - The main AGNI executable
 * `LICENSE.txt`     - License for use and re-use
+* `get_fastchem.sh` - Download and setup FastChem
+* `get_socrates.sh` - Download and setup SOCRATES
+* `get_data.sh`     - Download input data files
 * `deps/`           - Package build scripts
 * `docs/`           - Documentation source files
 * `misc/`           - Miscellaneous files
-* `out/`            - Model output
+* `out/`            - Model output files
 * `res/`            - Resources (configs, thermodynamic data, etc.)
 * `src/`            - Package source code
 * `test/`           - Package tests
 * `tutorials/`      - Notebooks and tutorials
-* `.github/`        - GitHub workflows
-* `.vscode/`        - Visual Studio Code configuration 
 

deps/build.jl

@@ -1,15 +1,25 @@
 # Build AGNI
+ROOT_DIR=abspath(joinpath(dirname(abspath(PROGRAM_FILE)),".."))
+println("ROOT_DIR = $ROOT_DIR")
 
 # Find socrates
 RAD_DIR = abspath(ENV["RAD_DIR"])
+println("RAD_DIR = $RAD_DIR")
 
 # Generate wrappers
+println("Generate wrappers")
 wrap = joinpath(RAD_DIR, "julia/src/generate_wrappers.jl")
 include(wrap)
 
 # Build libSOCRATES
+println("Build libSOCRATES")
 cd(joinpath(RAD_DIR,"julia/lib/")) do 
     run(`make`)
 end 
 
+# Download basic data 
+println("Get data")
+get_data = joinpath(ROOT_DIR,"get_data.sh")
+run(`bash $get_data basic`)
 
+println("Build completed")

docs/make.jl

@@ -19,7 +19,7 @@ makedocs(
         "usage.md",
         "examples/index.md",
         "troubleshooting.md",
-        "manual/index.md"
+        "Development" => "manual/index.md"
     ]
 )
 

docs/src/manual/index.md

@@ -1,4 +1,19 @@
-# Manual
+# Development manual
 
-This page documents functions and data structures within the code.
+## Contributing 
+If you are interested in contributing to the model, please contact the developers using the information on the main page.
+
+## Coding style 
+- Indentation uses 4 spaces, no tabs.
+- Function names should be lowercase, with words separated by underscores .
+- Lines should aim to have a length of no more than 92 characters.
+- All functions should have docstrings, ideally with Arguments and Returns listed.
+- More comments are always better, even if they seem redundant.
+- Use type hinting where possible.
+- Print statements should be made through the logger where possible.
+- The core package code should not contain global variables, except in the phys module.
+
+## Code reference
+
+*To be completed*.
 

docs/src/model/index.md

@@ -86,7 +86,7 @@ T_s
 ```
 where $T_s$ is the surface temperature. Cell-edge temperatures in the bulk atmosphere are interpolated using the [PCHIP algorithm](https://epubs.siam.org/doi/10.1137/0905021), which avoids Runge's phenomenon and overshooting. The bottom- and top-most cell edge temperatures are extrapolated by estimation of $dT/d \log p$. Cell properties (heat capacity, gravity, density, average molecular weight, etc.) are consistently updated at each evaluation of $\bm{r}$. Condensation/rainout are also handled at each evaluation of $\bm{r}$ in order to avoid supersaturation.
 
-The model converges when the cost function $c(\bm{x}) = \|\bm{r}\|$ satisfies the condition 
+The model converges when the cost function $c(\bm{x}) = \sqrt[6]{\sum_i |r_i|^6}$ satisfies the condition 
 ```math
 c(\bm{x}) < c_a + c_r \cdot \underset{i}{\max} \text{ } |F_i|
 ```

docs/src/setup.md

@@ -3,13 +3,16 @@ This page outlines requirements and installation steps for the code. Currently,
 GNU/Linux and MacOS (including ARM) are supported. 
 
 ## Requirements
-* [Julia](https://julialang.org/downloads/) 
-* [SOCRATES](https://github.com/nichollsh/SOCRATES) - see instructions below
+* gfortran 
+* NetCDF library for FORTRAN
+* make
+* curl
 
 !!! warning
     Do not install Julia using your system package manager. Install only from julialang.org
 
 ## Installation
+Follow the steps below in order to setup the code.
 1. Install Julia: `curl -fsSL https://install.julialang.org | sh`
 2. Download AGNI: `git clone https://github.com/nichollsh/AGNI.git`
 3. Change directory: `cd AGNI`
@@ -18,16 +21,19 @@ GNU/Linux and MacOS (including ARM) are supported.
     - Run `source get_socrates.sh`    
 5. `julia -e 'using Pkg; Pkg.activate("."); Pkg.build()'`
 AGNI is now installed as a package into a Julia environment in the AGNI
-directory. You should run the tests next.
+directory. This will also have downloaded some input data. You should run the tests next.
 
 !!! tip 
     The `get_socrates` script automatically adds the radiation code to your
     environment with the variable `RAD_DIR`. This needs to be set whenever 
     AGNI is being used.
 
 ## Testing
-Run `julia ./test/runtests.jl ` in your terminal. This will print information 
-on whether tests passed or failed.   
+Now try running the tests in your terminal. 
+```bash 
+julia ./test/runtests.jl
+```
+This will print information on whether tests passed or failed.   
 
 ## Using the code
 See [Running the model](@ref) for information on using the code.    

docs/src/troubleshooting.md

@@ -2,18 +2,35 @@
 This page may be useful if you are having problems. However, I would suggest that 
 you also double check the [Getting started](@ref) instructions.
 
-## Julia errors on start, potentially relating to the CURL library
+## Julia errors on start, potentially referencing the CURL library
 It is important that the shell environment variable `LD_LIBRARY_PATH` is 
 not set when running AGNI. This will cause Julia to use the wrong libraries, 
-which will certainly cause problems. You can unset this variable or reset 
-it via: `unset LD_LIBRARY_PATH` or `export LD_LIBRARY_PATH=""`.
+which will causes problems. You can unset this variable or reset using either of the
+following commands 
+```bash
+unset LD_LIBRARY_PATH
+export LD_LIBRARY_PATH=""
+```
+If this does not help, it's possible that you are using a Julia distribution provided by
+your system package manager. It's important that you only use Julia distributed from the 
+official website.
+
 
 ## Cannot find SOCRATES
 Check the installation instructions. Have you set `RAD_DIR`? Try running
 `l_run_cdf` in the terminal; if this fails, then SOCRATES has not compiled
 or you haven't added it to your `PATH`.
 
 
+## Spectral file does not exist
+Check the path in the configuration file. Download additional spectral files using the
+`get_data` script in the AGNI root directory. For example, for additional pure-steam 
+spectral files you would run
+```bash 
+./get_data.sh steam
+```
+
+
 ## Finally...
 If you are still stuck, or feel that there is a problem with the code, then 
 you can contact the authors using the information on the main page.

docs/src/usage.md

@@ -2,6 +2,15 @@
 First, follow the [Getting started](@ref) instructions. Only read-on once you 
 have confirmed that the code is working.  
 
+## Input data files
+The minimal input data required to run the model will have been downloaded automatically. 
+If you require more data, such as additional stellar spectra or opacities, then these can
+also be easily obtained using the `get_data` script in the AGNI root directory. To see how
+to use this script, run it without arguments like so:
+```bash 
+./get_data 
+```
+
 ## Tutorials
 There are Jupyter notebooks containing tutorials in the `tutorials/` directory 
 of the repository.
@@ -36,6 +45,8 @@ Broadly, the configuration files are broken up into four sections:
 * `[plots]` - which plots should be produced
 
 Some parameters:
+* `files.input_sf` is the file path to the "spectral file" containing opacity data. Several spectral files are packged with AGNI, but you can find more online via the [Open Science Framework](https://osf.io/vehxg/).
+
 * `execution.solution_type` tells the model which state to solve for. The allowed values (integers) are...
      - 1 : zero flux divergence at fixed `tmp_surf`
      - 2 : zero flux divergence, with `tmp_surf` set such that the conductive skin (CBL) conserves energy flux
@@ -48,12 +59,13 @@ Some parameters:
      - `levenberg` : the Levenberg–Marquardt algorithm is used 
 
 * `execution.initial_state` describes the initial temperature profile applied to the atmosphere. This is a list of strings which are applied in the given order, which allows the user to describe a specific state as required. The descriptors are listed below, some of which take a single argument that needs to immediately follow the descriptor in the list order.
-     - `dry` : integrate the dry adiabatic lapse rate from the surface upwards
-     - `str`, `arg` : apply an isothermal stratosphere at `arg` kelvin
-     - `iso`, `arg` : set the whole atmosphere to be isothermal at `arg` kelvin
-     - `csv`, `arg` : set the temperature profile using the CSV file at the file path `arg`
-     - `con`, `arg` : apply Clausius-Clapeyron saturation curve for the gas `arg`
-     - `sat` : ensure that no supersaturation occurs at the surface by removing gases as required    
+     - `dry`              : integrate the dry adiabatic lapse rate from the surface upwards
+     - `str`,       `arg` : apply an isothermal stratosphere at `arg` kelvin
+     - `iso`,       `arg` : set the whole atmosphere to be isothermal at `arg` kelvin
+     - `csv`,       `arg` : set the temperature profile using the CSV file at the file path `arg`
+     - `sat`,       `arg` : apply Clausius-Clapeyron saturation curve for the gas `arg`
+     - `ncdf`,      `arg` : load profile from the NetCDF file located at `arg`
+     - `loglin`,    `arg` : log-linear profile between `tmp_surf` at the bottom and `arg` at the top
 
     For example, setting `initial_state = ["dry", "sat", "H2O", "str", "180"]` will set T(p) to follow the dry adiabat from the surface, the water condensation curve above that, and then to be isothermal at 180 K until the top of the model.
 

get_data.sh

@@ -0,0 +1,111 @@
+#!/bin/bash
+# Download and unpack required and/or optional data
+# All files can be found on OSF at https://osf.io/8dumn/
+
+# Check that curl is installed 
+if ! [ -x "$(command -v curl)" ]; then
+  echo 'ERROR: curl is not installed.' >&2
+  exit 1
+fi
+
+# Root and resources folders 
+root=$(dirname $(realpath $0))
+res="$root/res/"
+
+# Make basic data folders 
+mkdir -p $res 
+mkdir -p "$res/spectral_files"
+mkdir -p "$res/stellar_spectra"
+
+# Help strings
+help_basic="Get the basic data required to run the model"
+help_highres="Get a spectral file with many high-resolution opacities"
+help_steam="Get pure-steam spectral files"
+help_stellar="Get a collection of stellar spectra"
+help="\
+Helper script used to download and unpack data used to run the model.
+
+Call structure:
+    ./get_data [TARGET]
+
+Where [TARGET] can be any of the following:
+    basic 
+        $help_basic
+    highres
+        $help_highres
+    steam
+        $help_steam
+    stellar
+        $help_stellar
+"
+
+# Generic OSF downloader function 
+function osf {
+    # $1 = OSF identifier
+    # $2 = target folder 
+    # $3 = target filename
+
+    # target file path
+    tgt="$2/$3"
+    rm -f $tgt
+    echo "    $1 > $tgt"
+
+    # get data
+    mkdir -p $2
+    curl -LsS "https://osf.io/download/$1/" > $tgt
+}
+
+# Handle user input 
+case $1 in
+    "basic")
+        echo $help_basic
+
+        osf qmp4e $res/spectral_files/Oak/318/ Oak.sf
+        osf 5fxr7 $res/spectral_files/Oak/318/ Oak.sf_k
+
+        osf heuza $res/spectral_files/Dayspring/48/ Dayspring.sf
+        osf c5jv3 $res/spectral_files/Dayspring/48/ Dayspring.sf_k
+
+        osf b5gsh $res/spectral_files/Dayspring/256/ Dayspring.sf
+        osf dn6wh $res/spectral_files/Dayspring/256/ Dayspring.sf_k
+
+        osf 2qdu8 $res/stellar_spectra sun.txt
+        ;;
+
+    "highres")
+        echo $help_highres
+
+        osf p672d $res/spectral_files/Honeyside/4096/ Honeyside.sf
+        osf ujb4z $res/spectral_files/Honeyside/4096/ Honeyside.sf_k
+        ;;
+
+    "steam")
+        echo $help_steam
+
+        osf 6rvfe $res/spectral_files/Frostflow/16/ Frostflow.sf
+        osf kxve8 $res/spectral_files/Frostflow/16/ Frostflow.sf_k
+
+        osf 9n6mw $res/spectral_files/Frostflow/48/ Frostflow.sf
+        osf xfap8 $res/spectral_files/Frostflow/48/ Frostflow.sf_k
+
+        osf mnvyq $res/spectral_files/Frostflow/256/ Frostflow.sf
+        osf tzsgc $res/spectral_files/Frostflow/256/ Frostflow.sf_k
+        ;;
+
+    "stellar")
+        echo $help_stellar 
+        osf mabp2 $res/stellar_spectra trappist-1.txt
+        osf rk7mj $res/stellar_spectra eps-eri.txt
+        osf agsrq $res/stellar_spectra hd97658.txt
+        osf ehfsy $res/stellar_spectra gj1214.txt
+        ;;
+
+    *)
+        echo "$help"
+        exit 1
+        ;;
+esac
+
+echo "Done!"
+
+exit 0

get_fastchem.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+# Download and compile fastchem
 
 # Download via HTTPS only
 fcpath="fastchem"

get_socrates.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+# Download and compile socrates
 
 # Check SSH access to GitHub
 ssh -T [email protected]