Merge branch 'main' of github.com:FormingWorlds/Erebus.jl

Merge README.md edit

.github/workflows/CI.yml

@@ -19,7 +19,7 @@ jobs:
       matrix:
         version:
           # - '1.0'
-          - '1.9'
+          - '1.10'
           # - 'nightly'
         os:
           - ubuntu-latest
@@ -39,18 +39,6 @@ jobs:
       - uses: julia-actions/julia-runtest@v1
       - uses: julia-actions/julia-processcoverage@v1
       - uses: codecov/codecov-action@v3
-
-  # Documenter:
-  #   permissions:
-  #     contents: write
-  #   name: Documentation
-  #   runs-on: ubuntu-latest
-  #   steps:
-  #     - uses: actions/checkout@v3
-  #     - uses: julia-actions/julia-buildpkg@v1
-  #     - uses: julia-actions/julia-docdeploy@v1
-  #       env:
-  #         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
   docs:
     name: Documentation
@@ -61,7 +49,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: julia-actions/setup-julia@v1
         with:
-          version: '1.9'
+          version: '1.10'
       - name: Install dependencies
         run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
       - name: Build and deploy

README.md

@@ -14,26 +14,53 @@
 - [License](#license)
 
 ## Introduction
-`Erebus.jl` is a Julia package developed for computational hydrology simulations in planetesimals. The package is designed to model fluid flow in planetesimals, accounting for various factors such as planetesimal composition, mineralogical and hydrodynamic properties, temperature curves, reaction equations, and other relevant parameters[^1][^2].
+`Erebus.jl` is a Julia package for simulating the geophysical evolution of planetesimals, focusing on two-phase fluid flow. It takes into account factors such as composition, mineralogical and hydrodynamic properties, temperature curves, and reaction rates[^1][^2].
 
 ## Installation
-To install `Erebus.jl`, you need to have Julia installed on your system. You can add the package using Julia's package manager. Here's how to do it:
+Ensure you have a current version of Julia installed on your system. You can add `Erebus.jl` using Julia's native package manager as follows:
 
 ```julia
 using Pkg
-Pkg.add("Erebus")
+Pkg.add(url="https://github.com/FormingWorlds/Erebus.jl.git")
 ```
 
 ## Usage
-After installation, you can import and use the package in your Julia scripts as follows:
+
+### Simulation parameters
+Modify the simulation parameters in [```src/constants.jl```](src/constants.jl) as needed. For automated unit/CI testing, refer to [```src/test_constants.jl```](src/test_constants.jl). For production simulation runs, start with the parameters in [```src/prod_constants.jl```](src/prod_constants.jl).
+
+### Complete simulation runs
+Initiate a simulation run from the terminal as follows:
+```
+julia -O3 --tauto launch.jl /PATH/TO/OUTPUT/
+```
+The `-O3` and `--tauto` flags are used for optimization and automatic threading respectively. All intermediate simulation data is written into HDF-5 compatible ```.jld2``` files in the output directory for later analysis and plotting. The log file ```Erebus_run.log``` in the output directory contains relevant simulation progress and parameters.
+
+### Manual operations and experiments
+After installation, you can import and manually use the package in your Julia scripts as follows:
 
 ```julia
 using Erebus
 
 # Your code here
 ```
-7
-Please refer to the documentation for detailed information on the functions and features provided by `Erebus.jl`.
+
+Refer to the [linked documentation](https://formingworlds.github.io/Erebus.jl/dev) for detailed information on the internal module functions and features provided by `Erebus.jl`.
+
+### Plotting results
+
+Use the helper script ```generate_plots.jl``` to generate plots by typing:
+```
+julia generate_plots.jl /PATH/TO/OUTPUT/
+```
+
+The resulting ```.pdf``` plot files are stored in the same directory as the simulation output. Generate animations using the helper script ```generate_animations.jl``` with the command:
+```
+julia generate_animations.jl /PATH/TO/OUTPUT/
+```
+The resulting ```.mp4``` animation files are stored in the same directory as the simulation output.
+
+Note: These helper scripts are independent of the ```Erebus.jl``` package and are provided as-is. They have their own dependencies which need to be fulfilled manually based on your Julia installation.
 
 ## Contributing
 Contributions to `Erebus.jl` are welcome. If you find a bug or have an idea for an improvement or new feature, please open an issue to discuss it. If you'd like to contribute code, please fork the repository, make your changes, and submit a pull request.
@@ -42,5 +69,5 @@ Contributions to `Erebus.jl` are welcome. If you find a bug or have an idea for
 `Erebus.jl` is licensed under the Apache 2.0 license. Please see the `LICENSE` file for more details.
 
 Citations:
-[^1]: https://doi.org/10.5281/zenodo.7058229
-[^2]: https://doi.org/10.1017/9781316534243
+[^1]: For more information on the simulation code and proof-of-concept experiments, refer to the report https://doi.org/10.5281/zenodo.7058229
+[^2]: For more information on the overall ansatz, refer to the book https://doi.org/10.1017/9781316534243