Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Switch docs over to Vitepress #59

Merged
merged 11 commits into from
Sep 24, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -28,3 +28,6 @@ Manifest.toml
.vscode/settings.json
*.jld2
/docs/notebooks
/docs/node_modules
docs/package-lock.json
docs/package.json
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@

[![Jutul Darcy logo](https://github.com/sintefmath/JutulDarcy.jl/raw/main/docs/src/assets/logo_wide.png)](https://sintefmath.github.io/JutulDarcy.jl/dev/)

*Clicking the logo sends you to the docs!*
> [!TIP]
> Visit the docs at https://sintefmath.github.io/JutulDarcy.jl/dev/

# Reservoir simulation in Julia

Expand Down Expand Up @@ -83,7 +84,7 @@ Cases with CPR used hypre as the AMG solver. OYMPUS1 refers to realization 1 fro

The main paper describing `JutulDarcy.jl` is *JutulDarcy.jl - a Fully Differentiable High-Performance Reservoir Simulator Based on Automatic Differentiation*:

```latex
```bibtex
@article{jutuldarcy_ecmor_2024,
author = "M{\o}yner, O.",
title = "JutulDarcy.jl - a Fully Differentiable High-Performance Reservoir Simulator Based on Automatic Differentiation",
Expand Down
1 change: 1 addition & 0 deletions docs/Project.toml
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
GLMakie = "e9467ef8-e4e7-5192-8a1a-b1aee30e663a"
GeoEnergyIO = "3b1dd628-313a-45bb-9d8d-8f3c48dcb5d4"
GraphMakie = "1ecd5474-83a3-4783-bb4f-06765db800d2"
Expand Down
100 changes: 62 additions & 38 deletions docs/make.jl
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,10 @@ using Literate
using Documenter

using DocumenterCitations
using DocumenterVitepress
##
cd(@__DIR__)
function build_jutul_darcy_docs(build_format = nothing; build_examples = true, build_notebooks = build_examples, clean = true)
function build_jutul_darcy_docs(build_format = nothing; build_examples = true, build_validation_examples = build_examples, 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"))
Expand All @@ -17,17 +18,17 @@ function build_jutul_darcy_docs(build_format = nothing; build_examples = true, b
# 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",
"Intro: Gravity segregation" => "two_phase_gravity_segregation",
"Intro: Two-phase Buckley-Leverett" => "two_phase_buckley_leverett",
"Intro: Wells" => "wells_intro",
"Intro: Simulating Eclipse/DATA input files" => "data_input_file",
"Intro: Sensitivities in JutulDarcy" => "intro_sensitivities",
"Intro: Compositional flow" => "co2_brine_2d_vertical",
"Quarter-five-spot with variation" => "five_spot_ensemble",
"Gravity circulation with CPR preconditioner" => "two_phase_unstable_gravity",
"Intro to wells" => "wells_intro",
"Intro to sensitivities in JutulDarcy" => "intro_sensitivities",
"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",
"Parameter matching of Buckley-Leverett" => "optimize_simple_bl",
"Validation: SPE1" => "validation_spe1",
"Validation: SPE9" => "validation_spe9",
"Validation: Compositional" => "validation_compositional",
Expand All @@ -37,6 +38,8 @@ function build_jutul_darcy_docs(build_format = nothing; build_examples = true, b
"Validation: MRST input files" => "validation_mrst"
]
examples_markdown = []
validation_markdown = []
intros_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 "*
Expand All @@ -58,8 +61,22 @@ function build_jutul_darcy_docs(build_format = nothing; build_examples = true, b
for (ex, pth) in examples
in_pth = example_path(pth)
out_dir = joinpath(@__DIR__, "src", "examples")
if build_examples
push!(examples_markdown, ex => joinpath("examples", "$pth.md"))
is_validation = startswith(ex, "Validation:")
is_intro = startswith(ex, "Intro: ")
is_example = !(is_intro || is_validation)
if is_validation
ex_dest = validation_markdown
do_build = build_validation_examples
else
if is_intro
ex_dest = intros_markdown
else
ex_dest = examples_markdown
end
do_build = build_examples
end
if do_build
push!(ex_dest, ex => joinpath("examples", "$pth.md"))
upd(content) = update_footer(content, pth)
Literate.markdown(in_pth, out_dir, preprocess = upd)
end
Expand All @@ -69,13 +86,19 @@ function build_jutul_darcy_docs(build_format = nothing; build_examples = true, b
end
## Docs
if isnothing(build_format)
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"],
)
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
end
makedocs(;
modules=[JutulDarcy, Jutul],
Expand All @@ -89,41 +112,42 @@ 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"
],
"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",
],
"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",
],
"Examples: Introduction" => intros_markdown,
"Examples: Usage" => examples_markdown,
"Examples: Validation" => validation_markdown,
"Advanced usage" => [
"man/advanced/mpi.md",
"man/advanced/compiled.md"
],
"Reference" => [
# "Internals" => "ref/internals.md",
"Jutul functions" => "ref/jutul.md"
],
"Additional information "=> [
"References" => "extras/refs.md",
"FAQ" => "extras/faq.md"
]
],
)

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
##
# build_jutul_darcy_docs(build_examples = false, build_validation_examples = false)
build_jutul_darcy_docs()

# ```@autodocs
Expand Down
Binary file added docs/src/assets/favicon.ico
Binary file not shown.
Binary file modified docs/src/assets/logo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/src/assets/logo_compact.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/src/assets/logo_tight.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
119 changes: 96 additions & 23 deletions docs/src/index.md
Original file line number Diff line number Diff line change
@@ -1,41 +1,114 @@
# JutulDarcy.jl - reservoir simulation and porous media flow in Julia
````@raw html
---
# https://vitepress.dev/reference/default-theme-home-page
layout: home

```@meta
CurrentModule = JutulDarcy
```
hero:
name: JutulDarcy
text: Re-thinking reservoir simulation in Julia
image:
src: logo.png
alt: JutulDarcy
tagline: High-performance porous media and reservoir simulator based on automatic differentiation
actions:
- theme: brand
text: Getting started
link: /man/intro
- theme: alt
text: View on Github
link: https://github.com/sintefmath/JutulDarcy.jl
- theme: alt
text: Run .DATA file
link: /examples/data_input_file

```@meta
DocTestSetup = quote
using Jutul;
using JutulDarcy;
end
```
features:
- icon: 💥
title: Physical systems
details: Immiscible, compositional, geothermal and black-oil flow
link: /man/basics/systems

- icon: ⚙️
title: Differentiability
details: Compute sensitivities of parameters with high-performance adjoint method
link: /examples/intro_sensitivities

- icon: 🏃
title: High performance
details: Fast execution with support for MPI and thread parallelism
link: /man/advanced/mpi
---
````

## What is this?

Documentation for [JutulDarcy.jl](https://github.com/sintefmath/JutulDarcy.jl). The documentation consists of a mixture of technical documentation, docstrings and examples. The examples are sorted by complexity. We suggest you start with [Gravity segregation example](Gravity segregation example).
JutulDarcy.jl is a general high-performance purpose porous media simulator toolbox (CO2 sequestration, gas/H2 storage, oil/gas fields) written in [Julia](https://julialang.org/) based on [Jutul.jl](https://github.com/sintefmath/Jutul.jl), developed by the [Applied Computational Science group](https://www.sintef.no/en/digital/departments-new/applied-mathematics/applied-computational-sciences/) at [SINTEF Digital](https://www.sintef.no/en/digital/).

To generate a folder that contains the examples locally, you can run the following code to create a folder `jutuldarcy_examples` in your current working directory:
A few highlights:

- Immiscible, black-oil, compositional, CO2-brine and geothermal systems
- Fully differentiable through adjoint method
- High performance, with optional support for compiling MPI parallel binaries
- Consistent discretizations
- Industry standard input formats - or make your own model as a script
- 3D visualization and tools for post-processing of simulation results

## Quick start guide

[Getting started](man/intro) is the main setup guide that includes the basics of installing Julia and creating a Julia environment for `JutulDarcy.jl`, written for users who may not already be familiar with Julia package management.

If you want to get started quickly: Install [Julia](https://julialang.org/) and add the following packages together
with a Makie backend library to your environment of choice using Julia's package manager `Pkg`:

```julia
using JutulDarcy
generate_jutuldarcy_examples()
using Pkg
Pkg.add("GLMakie") # Plotting
Pkg.add("Jutul") # Base package
Pkg.add("JutulDarcy") # Reservoir simulator
```

Alternatively, a folder can be specified if you want the examples to be placed outside your present working directory:
To verify that everything is working, we have a minimal example that runs a industry standard input file and produces interactive plots. Note that interactive plotting requires `GLMakie`, which may not work if you are running Julia over SSH.

::: details Show me the code

```@example
using JutulDarcy, GLMakie
spe9_dir = JutulDarcy.GeoEnergyIO.test_input_file_path("SPE9")
file_path = joinpath(spe9_dir, "SPE9.DATA")
case = setup_case_from_data_file(file_path)
result = simulate_reservoir(case)
plot_reservoir_simulation_result(case.model, result)
```
:::

To get access to all the examples, you can generate a folder that contains the examples locally, you can run the following code to create a folder `jutuldarcy_examples` in your current working directory:

```julia
using JutulDarcy
generate_jutuldarcy_examples("/home/username/")
generate_jutuldarcy_examples()
```

JutulDarcy builds upon the general features found in [Jutul.jl](https://github.com/sintefmath/Jutul.jl). You may also find it useful to look at the [Jutul.jl documentation](https://sintefmath.github.io/Jutul.jl/dev/).
These examples can then be run using `include("jutuldarcy_examples/example_name.jl")` or opened in an editor to be run line by line. Alternatively, you can download all examples as [Jupyter Notebooks](https://github.com/sintefmath/JutulDarcy.jl/tree/gh-pages/dev/examples).

## Package docstring
## Citing JutulDarcy

```@docs
JutulDarcy
```
If you use JutulDarcy for a scientific publication, please cite [the main paper](https://doi.org/10.3997/2214-4609.202437111) the following way:

> O. Møyner, (2024). JutulDarcy.jl - a Fully Differentiable High-Performance Reservoir Simulator Based on Automatic Differentiation. ECMOR 2024, [https://doi.org/10.3997/2214-4609.202437111](https://doi.org/10.3997/2214-4609.202437111)

## Index
```@index
::: details Show BibTeX

```bibtex
@article{jutuldarcy_ecmor_2024,
author = "M{\o}yner, O.",
title = "JutulDarcy.jl - a Fully Differentiable High-Performance Reservoir Simulator Based on Automatic Differentiation",
year = "2024",
volume = "2024",
number = "1",
pages = "1-9",
doi = "https://doi.org/10.3997/2214-4609.202437111",
publisher = "European Association of Geoscientists \& Engineers",
issn = "2214-4609",
}
```

:::
24 changes: 20 additions & 4 deletions docs/src/man/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@

## Installing JutulDarcy

To get started with JutulDarcy, you must install Julia (1.9+ recommended) and the package itself. Julia uses environments to manage packages. If you are not familiar with this concept, we recommend the [Pkg documentation](https://pkgdocs.julialang.org/v1/environments/).
To get started with JutulDarcy, you must install [the Julia programming language](https://julialang.org/). We recommend the latest stable release, but at least version 1.9 is required. Julia uses environments to manage packages. If you are not familiar with this concept, we recommend the [Pkg documentation](https://pkgdocs.julialang.org/v1/environments/).

### Setting up an environment

To set up an environment you can create a folder and open Julia with that project as a runtime argument. The environment is persistent: If you start Julia from that folder again, the same packages will be installed. For this reason, it is sufficient to do this process once.
To set up an environment you can create a folder and open Julia with that project as a runtime argument. The environment is persistent: If you start Julia in the same folder with the same project argument, the same packages will be installed. For this reason, it is sufficient to do this process once.

```bash
mkdir jutuldarcy_examples
cd jutuldarcy_examples
mkdir jutuldarcy_env
cd jutuldarcy_env
julia --project=.
```

Expand All @@ -19,6 +19,22 @@ using Pkg
Pkg.add("JutulDarcy")
```

You can then run any of the examples in the [`examples`](https://github.com/sintefmath/JutulDarcy.jl/tree/main/examples) directory by including them. The examples are sorted by complexity. We suggest you start with [Gravity segregation example](Intro: Gravity segregation example).

To generate a folder that contains the examples locally, you can run the following code to create a folder `jutuldarcy_examples` in your current working directory:

```julia
using JutulDarcy
generate_jutuldarcy_examples()
```

Alternatively, a folder can be specified if you want the examples to be placed outside your present working directory:

```julia
using JutulDarcy
generate_jutuldarcy_examples("/home/username/")
```

### Adding additional packages

We also rely heavily on the Jutul base package for some functionality, so we recommend that you also install it together with JutulDarcy:
Expand Down
Empty file removed docs/src/ref/internals.md
Empty file.
6 changes: 0 additions & 6 deletions src/JutulDarcy.jl
Original file line number Diff line number Diff line change
@@ -1,12 +1,6 @@

"""
$(README)

---
## Module exports:

$(EXPORTS)

"""
module JutulDarcy
export MultiPhaseSystem, ImmiscibleSystem, SinglePhaseSystem
Expand Down
Loading