Merge pull request #65 from sintefmath/dev

Documentation updates

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Olav Møyner
+Copyright (c) 2022 Olav Møyner, SINTEF Digital and Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Project.toml

@@ -1,7 +1,7 @@
 name = "JutulDarcy"
 uuid = "82210473-ab04-4dce-b31b-11573c4f8e0a"
 authors = ["Olav Møyner <[email protected]>"]
-version = "0.2.32"
+version = "0.2.33"
 
 [deps]
 AlgebraicMultigrid = "2169fc97-5a83-5252-b627-83903c6c433c"
@@ -54,7 +54,7 @@ DelimitedFiles = "1.6"
 DocStringExtensions = "0.9.3"
 ForwardDiff = "0.10.30"
 GLMakie = "0.10.0"
-GeoEnergyIO = "1.1.11"
+GeoEnergyIO = "1.1.12"
 HYPRE = "1.4.0"
 Jutul = "0.2.37"
 Krylov = "0.9.1"

docs/make.jl

@@ -7,7 +7,13 @@ using DocumenterCitations
 using DocumenterVitepress
 ##
 cd(@__DIR__)
-function build_jutul_darcy_docs(build_format = nothing; build_examples = true, build_validation_examples = build_examples, build_notebooks = build_examples, clean = true)
+function build_jutul_darcy_docs(build_format = nothing;
+        build_examples = true,
+        build_validation_examples = build_examples,
+        build_notebooks = true,
+        clean = true,
+        deploy = 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"))
@@ -26,6 +32,7 @@ function build_jutul_darcy_docs(build_format = nothing; build_examples = true, b
         "Intro: Compositional flow" => "co2_brine_2d_vertical",
         "Quarter-five-spot with variation" => "five_spot_ensemble",
         "Gravity circulation with CPR preconditioner" => "two_phase_unstable_gravity",
+        "CO2 property calculations" => "co2_props",
         "CO2 injection in saline aquifer" => "co2_sloped",
         "Compositional with five components" => "compositional_5components",
         "Parameter matching of Buckley-Leverett" => "optimize_simple_bl",
@@ -44,7 +51,7 @@ function build_jutul_darcy_docs(build_format = nothing; build_examples = true, b
         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 [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/dev/$pth.ipynb)"
+        "or as a [Jupyter Notebook](https://github.com/sintefmath/JutulDarcy.jl/blob/gh-pages/dev/final_site/notebooks/$pth.ipynb)"
     end
     if clean
         for (ex, pth) in examples
@@ -81,25 +88,20 @@ function build_jutul_darcy_docs(build_format = nothing; build_examples = true, b
             upd(content) = update_footer(content, pth)
             Literate.markdown(in_pth, out_dir, preprocess = upd)
         end
-        if build_notebooks
-            Literate.notebook(in_pth, notebook_dir, execute = false)
-        end
     end
     ## Docs
     if isnothing(build_format)
-        if false
-            build_format = Documenter.HTML(;
-                prettyurls=get(ENV, "CI", "false") == "true",
-                canonical="https://sintefmath.github.io/JutulDarcy.jl",
-                edit_link="main",
-                size_threshold_ignore = ["ref/jutul.md", "docstrings.md"],
-                assets=String["assets/citations.css"],
-            )
-        else
-            build_format = DocumenterVitepress.MarkdownVitepress(
-                repo = "https://github.com/sintefmath/JutulDarcy.jl",
-            )
-        end
+        # Old Documenter code in case we want to go back.
+        # build_format = Documenter.HTML(;
+        #     prettyurls=get(ENV, "CI", "false") == "true",
+        #     canonical="https://sintefmath.github.io/JutulDarcy.jl",
+        #     edit_link="main",
+        #     size_threshold_ignore = ["ref/jutul.md", "docstrings.md"],
+        #     assets=String["assets/citations.css"],
+        # )
+        build_format = DocumenterVitepress.MarkdownVitepress(
+            repo = "https://github.com/sintefmath/JutulDarcy.jl",
+        )
     end
     makedocs(;
         modules=[JutulDarcy, Jutul],
@@ -113,10 +115,9 @@ function build_jutul_darcy_docs(build_format = nothing; build_examples = true, b
             "Introduction" => [
                 "JutulDarcy.jl" => "index.md",
                 "Getting started" =>"man/intro.md",
-                "References" => "extras/refs.md",
-                "FAQ" => "extras/faq.md",
-                "Jutul functions" => "ref/jutul.md"
-                ],
+                "Your first JutulDarcy.jl simulation" => "man/first_ex.md",
+                "FAQ" => "extras/faq.md"
+            ],
             "Manual" => [
                     "man/highlevel.md",
                     "man/basics/input_files.md",
@@ -128,24 +129,38 @@ function build_jutul_darcy_docs(build_format = nothing; build_examples = true, b
                     "man/basics/secondary.md",
                     "man/basics/parameters.md",
                     "man/basics/plotting.md",
+                    "man/basics/utilities.md",
                     ],
+            "Further reading" => [
+                "man/advanced/mpi.md",
+                "man/advanced/compiled.md",
+                "Jutul functions" => "ref/jutul.md",
+                "Bibliography" => "extras/refs.md"
+            ],
             "Examples: Introduction" => intros_markdown,
             "Examples: Usage" => examples_markdown,
-            "Examples: Validation" => validation_markdown,
-            "Advanced usage" => [
-                "man/advanced/mpi.md",
-                "man/advanced/compiled.md"
-            ]
+            "Examples: Validation" => validation_markdown
         ],
     )
-
-    deploydocs(;
-        repo="github.com/sintefmath/JutulDarcy.jl.git",
-        devbranch="main",
-        target = "build", # this is where Vitepress stores its output
-        branch = "gh-pages",
-        push_preview = true
-    )
+    if build_notebooks
+        # Subfolder of final site build folder
+        notebook_dir = joinpath(@__DIR__, "build", "final_site", "notebooks")
+        mkpath(notebook_dir)
+        for (ex, pth) in examples
+            in_pth = example_path(pth)
+            @info "$ex Writing notebook to $notebook_dir"
+            Literate.notebook(in_pth, notebook_dir, execute = false)
+        end
+    end
+    if deploy
+        deploydocs(;
+            repo="github.com/sintefmath/JutulDarcy.jl.git",
+            devbranch="main",
+            target = "build", # this is where Vitepress stores its output
+            branch = "gh-pages",
+            push_preview = true
+        )
+    end
 end
 ##
 # build_jutul_darcy_docs(build_examples = false, build_validation_examples = false)

docs/src/extras/faq.md

@@ -1,8 +1,173 @@
 # Frequently asked questions
 
-!!! info "Note about units"
-    JutulDarcy does currently not make us of conversion factors or explicit
-    units can in principle use any consistent unit system. Some default scaling
-    of variables assume that the magnitude pressures and velocities roughly
-    match that of strict SI (e.g. Pascals and cubic meters per second). These
-    scaling factors are primarily used when iterative linear solvers are used.
+Here are a few common questions and possible answers.
+
+## Input and output
+
+### What input formats can JutulDarcy.jl use?
+
+1. DATA files (used by Eclipse, OPM Flow, tNavigator, Echelon and others) provided that the grid is given either as a corner-point GRDECL file or in TOPS format. As with most reservoir simulators, not all features of the original format are supported, but the code will let you know when unsupported features are encountered.
+2. Cases written out from [MRST](https://www.mrst.no/) through the `jutul` module.
+3. Cases written entirely in Julia using the basic `Jutul` and `JutulDarcy` data structures, as seen in the examples of the module.
+
+### What output formats does JutulDarcy.jl have?
+
+The simulator outputs results into standard Julia data structures (e.g. Vectors and Dicts) that can easily be written out using other Julia packages, for example in CSV format. We do not currently support binary formats output by commercial simulators.
+
+Simulation results are written to disk using [JLD2](https://github.com/JuliaIO/JLD2.jl), a subset of [HDF5](https://en.wikipedia.org/wiki/Hierarchical_Data_Format) commonly used in Julia for storing objects to disk.
+
+### How do I restart an interrupted simulation?
+
+JutulDarcy keeps everything in memory by default. This is not practical for larger models. If the argument `output_path` is set to a directory, JutulDarcy writes to the `JLD2` format (variant of HDF5).
+
+```julia
+# Note: set ENV["JUTUL_OUTPUT_PATH"] in your startup.jl first!
+pth = jutul_output_path("My_test_case")
+simulate_reservoir(case, output_path = pth)
+```
+
+If a output path is set, you can restart simulations:
+
+```julia
+# Restart from the last succesfully solved step, or return output if everything is simulated
+ws, states = simulate_reservoir(case, output_path = pth, restart = true)
+# Start from the beginning, overwriting files if already present
+ws, states = simulate_reservoir(case, output_path = pth, restart = false)
+# Restart from step 10 and throw error if step 9 is not already stored on disk.
+ws, states = simulate_reservoir(case, output_path = pth, restart = 10)
+```
+
+You can restart the simulation with different options for timestepping or tolerances.
+
+### How do I decide where output is stored?
+
+`Jutul.jl` contains a system for managing output folders. It is highly recommended that you amend your `startup.jl` file to include `ENV["JUTUL_OUTPUT_PATH"]` that points to where you want output to be stored. For example, on Windows usage of the output path mechanism may look something like this:
+
+```julia
+julia> ENV["JUTUL_OUTPUT_PATH"]
+"D:/jutul_output/"
+
+julia> jutul_output_path() # Randomly generated file name
+"D:/jutul_output/jutul/jl_DwpAvQTiLo"
+
+julia> jutul_output_path("mycase")
+"D:/jutul_output/jutul/mycase"
+
+julia> jutul_output_path("mycase", subfolder = "ensemble_name")
+"D:/jutul_output/ensemble_name/mycase"
+
+julia> jutul_output_path("mycase", subfolder = missing)
+"D:/jutul_output/mycase"
+```
+
+Or equivialent on a Linux system:
+
+```julia
+julia> ENV["JUTUL_OUTPUT_PATH"]
+"/home/username/jutul_output/"
+
+julia> jutul_output_path() # Randomly generated file name
+"/home/username/jutul_output/jutul/jl_DwpAvQTiLo"
+
+julia> jutul_output_path("mycase")
+"/home/username/jutul_output/jutul/mycase"
+
+julia> jutul_output_path("mycase", subfolder = "ensemble_name")
+"/home/username/jutul_output/ensemble_name/mycase"
+
+julia> jutul_output_path("mycase", subfolder = missing)
+"/home/username/jutul_output/mycase"
+```
+
+You can also just specify a full path and keep track of output folders yourself, but using the `jutul_output_path` mechanism will make it easier to write a script that can be run on another computer with different folder structure.
+
+### How do you get out more output from a simulation?
+
+The default outputs per cell are primary variables and total masses:
+
+```julia
+reservoir_model(model).output_variables
+3-element Vector{Symbol}:
+ :Pressure
+ :Saturations
+ :TotalMasses
+```
+
+You can push variables to this list, or ask the code to output all variables:
+
+```julia
+model2, = setup_reservoir_model(domain, sys, extra_outputs = true);
+reservoir_model(model2).output_variables
+7-element Vector{Symbol}:
+ :Pressure
+ :Saturations
+ :TotalMasses
+ :PhaseMassDensities
+ :RelativePermeabilities
+ :PhaseMobilities
+ :PhaseMassMobilities
+```
+
+Can also pass `extra_outputs = [:PhaseMobilities]`  to output specific variables.
+
+## Plotting
+
+### What is required for visualization?
+
+We use the wonderful [`Makie.jl`](https://docs.makie.org/) for both 2D and 3D plots. Generally `CairoMakie` is supported for non-interactive plotting and `GLMakie` is used for interactive plotting (especially 3D). The latter requires a working graphics context, which is not directly available when the code is run over for example SSH or on a server.
+
+For more details on the backends, see the[`Makie.jl` docs](https://docs.makie.org/stable/explanations/backends/backends)
+
+## Miscellaneous
+
+### Can you add feature X or format Y?
+
+If you have a feature you'd like to have supported, please file an
+[issue](https://github.com/JuliaIO/JLD2.jl/issues) with details on the format.
+`JutulDarcy` is developed primarily through contract research, so features are
+added as needed for ongoing projects where the simulator is in use. Posting an
+issue, especially if you have a clear reference to how something should be
+implemented is still very useful. It is also possible to fund the development
+for a specific feature, or to implement the feature yourself by asking for
+pointers on how to get started.
+
+### What units does JutulDarcy.jl use?
+
+JutulDarcy uses consistent units. This typically means that all your values must
+be input in strict SI. This means pressures in Pascal, temperatures in Kelvin
+and time in seconds. Note that this is very similar to the `METRIC` type of unit
+system seen in many commercial simulators, except that units of time is not
+given in days. This also impacts permeabilities, transmissibilities and
+viscosities, which will be much smaller than in metric where days are used.
+
+Reading of input files will automatically convert data to the correct units for simulation, but care must be taken when you are writing your own code. `Jutul.jl` contains unit conversion factors to make it easier to write code:
+
+```@example
+using Jutul
+p = convert_to_si(120.0, :bar)
+```
+
+You can also extract individual units and to the setup yourself:
+
+```@example
+using Jutul
+day, stb = si_units(:day, :stb)
+# convert to m^3/s:
+rate = 100.0stb/day
+```
+
+JutulDarcy does currently not make use of conversion factors or explicit
+units can in principle use any consistent unit system. Some default scaling
+of variables assume that the magnitude pressures and velocities roughly
+match that of strict SI (e.g. Pascals and cubic meters per second). These
+scaling factors are primarily used when iterative linear solvers are used.
+
+### Why write a new reservoir simulation code in Julia?
+
+We believe that reservoir simulation should be a *library* and not necessarily an application by itself. The future of porous media simulation is deeply integrated into other workflows, and not as an application that simply writes files to disk. As a part of experimentation in differentiable and flexible solvers using automatic differentiation that started with [MRST](https://www.mrst.no), Julia was the natural next step.
+
+### What is the license of JutulDarcy.jl?
+
+The code uses the [MIT license](https://en.wikipedia.org/wiki/MIT_License), a permissive license that requires attribution, but does not place limitations on commercial use or closed-source integration.
+
+The code uses a number of dependencies that can have other licenses and we make no guarantees that the entirety of the code made available by adding `JutulDarcy.jl` to a given Julia environment is all MIT licensed.

docs/src/extras/refs.md

@@ -1,4 +1,2 @@
-# References
-
 ```@bibliography
 ```

docs/src/man/advanced/compiled.md

@@ -1,3 +1,21 @@
 # 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).
+Scripts are interactive and useful for doing setup, simulation and post-processing in one file, but sometimes you want to run a big model unmodified from an input file:
+
+- As an alternative to a pure Julia workflow, `JutulDarcy.jl` can be compiled into a standalone reservoir simulator
+- This makes MPI simulations more ergonomic
+- Compiling the code saves time when running multiple simulations
+- The resulting executable is a standard command-line program - no Julia experience needed
+- Output is given in the same format as regular simulations, can load data by restarting a simulation from the same `output_path`
+
+This workflow uses [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).
+
+A few things to note:
+
+- The simulator comes with a set of shared library files and will be ~500 mb
+- Binaries will match platform (compiling under Linux gives you Linux binaries)
+- The repository has a script that runs small "representative" models
+- You can input small representative models in `precompile_jutul_darcy_mpi.jl` to make sure that compilation is avoided during simulation
+- By default, the script uses the default Julia MPI binary. On a cluster, the build script may have to be modified to use the MPI type of the cluster using [MPITrampoline.jl](https://github.com/eschnett/MPItrampoline)
+
+If you get it working on a complex MPI setup, feedback on your experience and PRs are very welcome.