Add front page and readthedocs configuration

_env/

_material/

_venv/

_site/

version: 2

build:

  os: ubuntu-22.04

  tools:

    python: "3.11"

mkdocs:

  configuration: mkdocs.yml

python:

  install:

    - requirements: requirements.txt

# Core Modules Overview

Before diving into grid tutorials, it helps to understand how DUNE is organized.

## Why Modules?

DUNE is split into modules so you can combine only what you need:

- small core dependencies for basic workflows,

- optional higher-level modules for specific discretizations,

- extension modules for special grids, I/O, and application domains.

This keeps projects flexible and avoids a monolithic framework structure.

## Core Module Roles

In this tutorial we start with the five core modules:

- `dune-common`: infrastructure, utilities, configuration, and base abstractions.

- `dune-geometry`: reference elements and geometry mappings.

- `dune-grid`: grid interface and concrete grid implementations.

- `dune-localfunctions`: local shape functions and basis-related local tools.

- `dune-istl`: iterative solvers, sparse linear algebra, and preconditioners.

## How They Fit Together

A typical first workflow looks like:

1. create or load a grid (`dune-grid`),

2. iterate entities and access geometry (`dune-grid` + `dune-geometry`),

3. define local finite element ingredients (`dune-localfunctions`),

4. assemble and solve linear systems (`dune-istl`),

5. use common infrastructure throughout (`dune-common`).

## What Comes Next

After this core layer, you can move to higher-level modules such as:

- `dune-functions` / `dune-assembler` for modern assembly workflows,

- `dune-fem` (including Python paths) for rapid model development,

- extension modules for grid managers, mesh I/O, and specialized transformations.

The next pages start with the grid concepts because they are the central entry point to most DUNE-based PDE codes.

# DUNE Tutorial

This tutorial is an entry point to the **Distributed and Unified Numerics Environment (DUNE)**.

It is designed to help you decide quickly:

- what DUNE is good at,

- how difficult setup is in practice,

- how to move from first compile to first PDE solve.

## Who This Is For

- Beginners who know C++ and basic FEM and want a realistic first contact with DUNE.

- Users from other frameworks (for example FEniCS, deal.II, Firedrake, MFEM) who want to map familiar workflows to DUNE concepts.

## What You Can Expect

If you follow the Getting Started and Core chapters, you should be able to:

1. set up a minimal DUNE core environment,

2. compile and run standalone examples,

3. solve a simple PDE within an afternoon,

4. understand where to go next for advanced discretizations and extensions.

## Scope and Roadmap

The tutorial is structured in layers:

1. **Getting Started**

   setup, first program, build workflow.

2. **Core Concepts**

   `dune-common`, `dune-geometry`, `dune-grid`, `dune-localfunctions`, `dune-istl`.

3. **First PDE and Time-Dependent Problems**

   a complete problem path from model to output.

4. **Advanced Discretizations and Solvers**

   transport, mixed methods, Stokes, DG, Krylov/AMG, block systems.

5. **Adaptivity, Parallelism, and Extensions**

   refinement, load balancing, mesh I/O, VTK, special grid modules.

6. **Migration Guides and Cookbook**

   practical patterns and framework translation hints.

Current focus is the core modules first. Extensions and specialized modules are introduced progressively.

## How To Start Reading

Recommended path:

1. `getting-started/overview.md`

2. `getting-started/installation.md`

3. `getting-started/first-program.md`

4. `core/grid.md` and neighboring core pages

If you want the fastest local setup for this tutorial, use:

```bash

./setup-env.sh

source _env/activate.sh

dunecontrol all

```

## Where To Learn More

- Official getting started: <https://www.dune-project.org/doc/gettingstarted/>

- Build from source: <https://www.dune-project.org/installation/installation-buildsrc/>

- External libraries: <https://www.dune-project.org/installation/external-libraries/>

- DUNE doxygen: <https://www.dune-project.org/doxygen/master/>

This site stays compact on purpose; official docs are the reference for full installation and module-specific details.

site_name: DUNE Tutorial

site_description: A progressive tutorial for the Distributed and Unified Numerics Environment (DUNE)

site_dir: _site

theme:

  name: material

  features:

nav:

  - Home: index.md

  - Getting Started:

      - Overview: getting-started/overview.md

      - Installation: getting-started/installation.md

      - First DUNE Program: getting-started/first-program.md

  - Core Concepts:

      - dune-common: core/common.md

      - dune-geometry: core/geometry.md

      - dune-grid: core/grid.md

      - dune-localfunctions: core/localfunctions.md

      - dune-istl: core/istl.md

  - First PDE (Poisson):

      - Model Problem: first-pde/model.md

      - Weak Formulation: first-pde/weak-form.md

      - Discretization: first-pde/discretization.md

      - Assembly and Solve: first-pde/assembly.md

      - Visualization: first-pde/output.md

  - Time Dependent Problems:

      - Heat Equation: time-dependent/heat.md

      - Time Stepping: time-dependent/timestepping.md

  - Advanced Discretizations:

      - Transport and Stabilization: advanced-discretizations/transport.md

      - Mixed Poisson: advanced-discretizations/mixed.md

      - Stokes: advanced-discretizations/stokes.md

      - DG Methods: advanced-discretizations/dg.md

  - Solvers and Preconditioners:

      - ISTL Basics: solvers/istl-basics.md

      - AMG and Krylov: solvers/krylov.md

      - Block Systems: solvers/blocksystems.md

      - Writing a Custom Preconditioner: solvers/custom-preconditioner.md

  - Adaptivity and Parallelism:

      - Grid Refinement: adaptivity-parallel/refinement.md

      - Error Indicators: adaptivity-parallel/error-estimation.md

      - Load Balancing: adaptivity-parallel/load-balancing.md

      - Domain Decomposition: adaptivity-parallel/domain-decomposition.md

  - dune-functions and dune-assembler:

      - Function Space Abstractions: dune-functions-assembler/functions.md

      - Assembly Framework: dune-functions-assembler/assembler.md

      - Comparison to PDELab: dune-functions-assembler/comparison.md

  - dune-fem and Python:

      - dune-fem Overview: dune-fem-python/overview.md

      - Python Prototyping: dune-fem-python/python.md

      - When to Use dune-fem: dune-fem-python/when.md

  - Extensions:

      - Grid Managers (ALUGrid, FoamGrid): extensions/grid-managers.md

      - Gmsh and Mesh IO: extensions/gmsh.md

      - VTK Output: extensions/vtk.md

      - Curved Grids and Transformations: extensions/curved.md

  - Migration Guides:

      - From FEniCS: migration-guides/fenics.md

      - From deal.II: migration-guides/dealii.md

      - From Firedrake: migration-guides/firedrake.md

  - Cookbook:

      - Parameter Files: cookbook/parameters.md

      - Traversing Intersections: cookbook/intersections.md

      - Custom Grid Functions: cookbook/gridfunctions.md

      - Performance Tips: cookbook/performance.md

      - First Program: getting-started/first-program.md

  - Core Modules:

      - Overview: core/overview.md

      - Grid Basics: core/grid.md

      - Grid Traversal: core/grid-traversal.md