Merge pull request #36 from sintefmath/doc-updates-2

Updates to docs + add CO2-brine model from CSP11

.gitignore

@@ -27,3 +27,4 @@ docs/src/examples/*
 Manifest.toml
 .vscode/settings.json
 *.jld2
+/docs/notebooks

Project.toml

@@ -1,7 +1,7 @@
 name = "JutulDarcy"
 uuid = "82210473-ab04-4dce-b31b-11573c4f8e0a"
 authors = ["Olav Møyner <[email protected]>"]
-version = "0.2.19"
+version = "0.2.20"
 
 [deps]
 AlgebraicMultigrid = "2169fc97-5a83-5252-b627-83903c6c433c"
@@ -51,7 +51,7 @@ ForwardDiff = "0.10.30"
 GLMakie = "0.9.2"
 GeoEnergyIO = "1"
 HYPRE = "1.4.0"
-Jutul = "0.2.22"
+Jutul = "0.2.28"
 Krylov = "0.9.1"
 LinearAlgebra = "1"
 LoopVectorization = "0.12.115"

docs/Project.toml

@@ -1,8 +1,10 @@
 [deps]
-GLMakie = "e9467ef8-e4e7-5192-8a1a-b1aee30e663a"
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
+GLMakie = "e9467ef8-e4e7-5192-8a1a-b1aee30e663a"
+GeoEnergyIO = "3b1dd628-313a-45bb-9d8d-8f3c48dcb5d4"
+HYPRE = "b5ffcf37-a2bd-41ab-a3da-4bd9bc8ad771"
 Jutul = "2b460a1a-8a2b-45b2-b125-b5c536396eb9"
 JutulDarcy = "82210473-ab04-4dce-b31b-11573c4f8e0a"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"

docs/make.jl

@@ -4,41 +4,62 @@ using Literate
 using Documenter
 
 using DocumenterCitations
-bib = CitationBibliography(joinpath(@__DIR__, "src", "refs.bib"))
-
-function build_jutul_darcy_docs(build_format = nothing; build_examples = true)
+##
+cd(@__DIR__)
+function build_jutul_darcy_docs(build_format = nothing; build_examples = true, build_notebooks = build_examples, clean = true)
     DocMeta.setdocmeta!(JutulDarcy, :DocTestSetup, :(using JutulDarcy; using Jutul); recursive=true)
     DocMeta.setdocmeta!(Jutul, :DocTestSetup, :(using Jutul); recursive=true)
+    bib = CitationBibliography(joinpath(@__DIR__, "src", "refs.bib"))
 
     ## Literate pass
     # Base directory
-    jutul_dir = joinpath(dirname(pathof(JutulDarcy)), "..")
+    jutul_dir = realpath(joinpath(@__DIR__, ".."))
     # Convert examples as .jl files to markdown
     examples = [
+        # "Intro" => "intro_example",
         "Gravity segregation" => "two_phase_gravity_segregation",
         "Two-phase Buckley-Leverett" => "two_phase_buckley_leverett",
         "Gravity circulation with CPR preconditioner" => "two_phase_unstable_gravity",
         "Intro to wells" => "wells_intro",
+        "CO2 injection in saline aquifer" => "co2_sloped",
+        "Simulating Eclipse/DATA input files" => "data_input_file",
         "Quarter-five-spot with variation" => "five_spot_ensemble",
         "Intro to compositional flow" => "co2_brine_2d_vertical",
         "Compositional with five components" => "compositional_5components",
         "Parameter optimization of Buckley-Leverett" => "optimize_simple_bl",
         "Validation of reservoir simulator" => "mrst_validation"
     ]
-    examples_markdown = ["Getting started" => "examples/intro.md"]
+    examples_markdown = []
     function update_footer(content, pth)
         return content*"\n\n # ## Example on GitHub\n "*
         "# If you would like to run this example yourself, it can be downloaded from "*
-        "[the JutulDarcy.jl GitHub repository](https://github.com/sintefmath/JutulDarcy.jl/blob/main/examples/$pth.jl)."
+        "the JutulDarcy.jl GitHub repository [as a script](https://github.com/sintefmath/JutulDarcy.jl/blob/main/examples/$pth.jl), "*
+        "or as a [Notebook](https://github.com/sintefmath/JutulDarcy.jl/blob/gh-pages/docs/notebooks/$pth.ipynb)"
     end
-    if build_examples
+    if clean
         for (ex, pth) in examples
-            in_pth = joinpath(jutul_dir, "examples", "$pth.jl")
-            out_dir = joinpath(jutul_dir, "docs", "src", "examples")
+            delpath = joinpath(@__DIR__, "src", "examples", "$pth.md")
+            if isfile(delpath)
+                println("Deleting generated example \"$ex\":\n\t$delpath")
+                rm(delpath)
+            else
+                println("Did not find generated example \"$ex\", skipping removal:\n\t$delpath")
+            end
+        end
+    end
+    example_path(pth) = joinpath(jutul_dir, "examples", "$pth.jl")
+    for (ex, pth) in examples
+        in_pth = example_path(pth)
+        if build_examples
+            out_dir = joinpath(@__DIR__, "src", "examples")
             push!(examples_markdown, ex => joinpath("examples", "$pth.md"))
             upd(content) = update_footer(content, pth)
             Literate.markdown(in_pth, out_dir, preprocess = upd)
         end
+        if build_notebooks
+            out_dir_notebooks = joinpath(@__DIR__, "notebooks")
+            Literate.notebook(in_pth, out_dir_notebooks)
+        end
     end
     ## Docs
     if isnothing(build_format)
@@ -58,25 +79,27 @@ function build_jutul_darcy_docs(build_format = nothing; build_examples = true)
         plugins=[bib],
         format=build_format,
         pages=[
-            "Home" => "index.md",
-            "Manual" => [
+            "Introduction" => [
+                "JutulDarcy.jl" => "index.md",
                 "Getting started" =>"man/intro.md",
-                "High-level functions" =>"man/highlevel.md",
-                "Input files" =>"man/input_files.md",
-                "Driving forces" =>"man/forces.md",
-                "Supported physical systems" =>"man/systems.md",
-                "Wells and controls" =>"man/wells.md",
-                "Solving the equations" => "man/solution.md",
-                "Primary variables" => "man/primary.md",
-                "Secondary variables (properties)" => "man/secondary.md",
-                "Parameters" => "man/parameters.md",
-                "Visualization" =>"man/plotting.md",
+                ],
+            "Examples" => examples_markdown,
+            "Manual" => [
+                "man/highlevel.md",
+                "man/basics/input_files.md",
+                "man/basics/forces.md",
+                "man/basics/systems.md",
+                "man/basics/wells.md",
+                "man/basics/solution.md",
+                "man/basics/primary.md",
+                "man/basics/secondary.md",
+                "man/basics/parameters.md",
+                "man/basics/plotting.md",
                 ],
             "Advanced usage" => [
-                "Parallel solves with MPI" =>"man/mpi.md",
-                "JutulDarcy.jl compiled app" =>"man/compiled.md"
+                "man/advanced/mpi.md",
+                "man/advanced/compiled.md"
             ],
-            "Examples" => examples_markdown,
             "Reference" => [
                 # "Internals" => "ref/internals.md",
                 "Jutul functions" => "ref/jutul.md"

docs/src/man/advanced/compiled.md

@@ -0,0 +1,3 @@
+# Standalone reservoir simulator
+
+It is possible build a standalone reservoir simulator using [PackageCompiler.jl](https://github.com/JuliaLang/PackageCompiler.jl). For more details and an example build file with keyword arguments, see [the JutulDarcyApps.jl repository](https://github.com/sintefmath/JutulDarcyApps.jl/tree/master/mpi_simulator).

docs/src/man/mpi.md → docs/src/man/advanced/mpi.md

@@ -1,4 +1,4 @@
-# Parallel solution using MPI.jl, PartitionedArrays.jl and HYPRE.jl
+# Multi-threading and MPI support
 
 JutulDarcy can use threads by default, but advanced options can improve performance significantly for larger models.
 
@@ -8,7 +8,7 @@ There are two main ways of exploiting multiple cores in Jutul/JutulDarcy: Thread
 
 ### MPI parallelization
 
-MPI parallelizes all aspects of the solver using domain decomposition and allows a simulation to be divided between multiple nodes in e.g. a supercomputer. It is significantly more cumbersome to use than standard simulations as the program must be launched in MPI mode. This is typically a non-interactive process where you launch your MPI processes and once they complete the simulation the result is available on disk.
+MPI parallelizes all aspects of the solver using domain decomposition and allows a simulation to be divided between multiple nodes in e.g. a supercomputer. It is significantly more cumbersome to use than standard simulations as the program must be launched in MPI mode. This is typically a non-interactive process where you launch your MPI processes and once they complete the simulation the result is available on disk. The MPI parallel option uses a combination of MPI.jl, PartitionedArrays.jl and HYPRE.jl.
 
 ### Thread parallelization
 

docs/src/man/basics/input_files.md

@@ -0,0 +1,43 @@
+
+# Input formats
+
+It is also possible to read cases that have been set up in MRST (see [`setup_case_from_mrst`](@ref) and [`simulate_mrst_case`](@ref)) or from .DATA files (see [`setup_case_from_data_file`](@ref) and [`simulate_data_file`](@ref))
+
+## MAT-files from the Matlab Reservoir Simulation Toolbox (MRST)
+
+### Simulation of .MAT files
+
+```@docs
+setup_case_from_mrst
+simulate_mrst_case
+```
+
+### MRST-specific types
+
+```@docs
+Jutul.MRSTWrapMesh
+```
+
+## DATA-files from commercial reservoir modelling software
+
+JutulDarcy can set up cases from Eclipse-type input files by making use of the [GeoEnergyIO.jl](https://github.com/sintefmath/GeoEnergyIO.jl) package for parsing. This package is a direct dependency of JutulDarcy and these cases can be simulated directly. If you want to parse the input files and possibly modify them in your Julia session before the case is simulated, we refer you to the [GeoEnergyIO Documentation](https://sintefmath.github.io/GeoEnergyIO.jl/dev/).
+
+If you want to directly simulate a file from disk, you can sue the high level functions that automatically parse the files for you:
+
+```@docs
+simulate_data_file
+setup_case_from_data_file
+JutulDarcy.setup_case_from_parsed_data
+```
+
+Reservoir simulator input files are highly complex and contain a great number of
+different keywords. JutulDarcy and GeoEnergyIO has extensive support for this
+format, but many keywords are missing or only partially supported. Sometimes
+cases can be made to run by removing keywords that do not impact simulation
+outcomes, or have very little impact. If you want a turnkey open source solution
+for simulation reservoir models you should also have a look at [OPM
+Flow](https://opm-project.org/).
+
+If you can share your input file or the missing keywords [in the issues
+section](https://github.com/sintefmath/JutulDarcy.jl/issues) it may be easier to
+figure out if a case can be supported.

docs/src/man/systems.md → docs/src/man/basics/systems.md

@@ -33,15 +33,21 @@ VaporPhase
 
 ### Implementation details
 
-In the above the discrete version of ``M_i`` is implemented in the update function for [`TotalMasses`](@ref) that should by convention be named [`JutulDarcy.update_total_masses!`](@ref). The discrete component fluxes are implemented by [`JutulDarcy.component_mass_fluxes!`](@ref).
+In the above the discrete version of ``M_i`` is implemented in the update function for [`JutulDarcy.TotalMasses`](@ref) that should by convention be named [`JutulDarcy.update_total_masses!`](@ref). The discrete component fluxes are implemented by [`JutulDarcy.component_mass_fluxes!`](@ref).
 
 ```@docs
+JutulDarcy.TotalMasses
 JutulDarcy.update_total_masses!
 JutulDarcy.component_mass_fluxes!
 ```
 
 The source terms are implemented by [`Jutul.apply_forces_to_equation!`](@ref) for boundary conditions and sources, and [`Jutul.update_cross_term_in_entity!`](@ref) for wells. We use Julia's multiple dispatch to pair the right implementation with the right physics system.
 
+```@docs
+Jutul.apply_forces_to_equation!
+Jutul.update_cross_term_in_entity!
+```
+
 ## Single-phase flow
 
 ```@docs
@@ -149,6 +155,10 @@ For additional details, please see Chapter 8 - Compositional Simulation with the
 !!! note "Compositional implementation"
     The [`MultiPhaseCompositionalSystemLV`](@ref) implements the compositional model. The primary variables for the most general case is the reference [`Pressure`](@ref), an [`ImmiscibleSaturation`](@ref) for the optional immiscible phase and ``M-1`` [`OverallMoleFractions`](@ref).
 
-## Thermal flow
+## Multi-phase thermal flow
 
-Currently experimental and undocumented. See [`ThermalSystem`](@ref) if you are feeling brave.
+```@docs
+reservoir_system
+ThermalSystem
+Jutul.CompositeSystem
+```

docs/src/man/wells.md → docs/src/man/basics/wells.md

@@ -4,6 +4,10 @@
 
 Wells can be set up using the convenience functions [`setup_well`](@ref) and [`setup_vertical_well`](@ref). These routines act on the output from [`reservoir_domain`](@ref) and can set up both types of wells. We recommend that you use these functions instead of manually calling the well constructors.
 
+```@docs
+JutulDarcy.WellGroup
+```
+
 ## Types of wells
 
 ### Simple wells
@@ -17,6 +21,7 @@ JutulDarcy.SimpleWell
 ### Multisegment wells
 
 ```@docs
+WellDomain
 MultiSegmentWell
 ```
 

docs/src/man/highlevel.md

@@ -4,6 +4,13 @@
 
 ### Meshes
 
+JutulDarcy can use meshes that supported by Jutul. This includes the Cartesian and Unstructured meshes as well as any meshes in the more general [Meshes.jl](https://github.com/JuliaGeometry/Meshes.jl) package.
+
+```@docs
+Jutul.CartesianMesh
+Jutul.UnstructuredMesh
+```
+
 ### Reservoir
 
 ```@docs
@@ -29,15 +36,12 @@ setup_reservoir_model
 setup_reservoir_state
 ```
 
-#### Why is initialization needed?
-
-#### Simple initialization
-
-#### Hydrostatic equilibriation
+TODO: Write about hydrostatic equilbriation.
 
 ## Simulation
 
 ```@docs
 simulate_reservoir
 setup_reservoir_simulator
+ReservoirSimResult
 ```