diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..a97459b --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,57 @@ +name: docs + +on: + push: + branches: [main] + pull_request: + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + + - uses: cachix/install-nix-action@v31 + with: + nix_path: nixpkgs=channel:nixos-26.05 + + - name: Configure GitHub Pages + uses: actions/configure-pages@v6 + + - name: Build documentation with Sphinx + env: + SOURCE_DATE_EPOCH: "1767225600" + run: | + nix shell \ + --impure \ + --expr 'with import {}; python3.withPackages (ps: [ ps.sphinx ps.furo ])' \ + -c sphinx-build -b html -W --keep-going doc/sphinx doc/sphinx/_build/html + + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v5 + with: + path: doc/sphinx/_build/html + + deploy: + if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main' + needs: build + permissions: + contents: read + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v5 diff --git a/README.md b/README.md index 7e6ab90..c3e7c71 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +![flecsolve logo](doc/sphinx/_static/flecsolve.svg) + The flecsolve package is a parallel computational framework for multi-physics application development using the open source [FleCSI](https://flecsi.github.io/flecsi/) programming system. Flecsolve employs design principles from the [AMP](https://github.com/AdvancedMultiPhysics/AMP) diff --git a/doc/sphinx/.gitignore b/doc/sphinx/.gitignore new file mode 100644 index 0000000..69fa449 --- /dev/null +++ b/doc/sphinx/.gitignore @@ -0,0 +1 @@ +_build/ diff --git a/doc/sphinx/Makefile b/doc/sphinx/Makefile new file mode 100644 index 0000000..1d2678f --- /dev/null +++ b/doc/sphinx/Makefile @@ -0,0 +1,16 @@ +# Minimal makefile for Sphinx documentation + +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build +override SOURCE_DATE_EPOCH = 1767225600 +export SOURCE_DATE_EPOCH + +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/sphinx/_static/flecsolve.svg b/doc/sphinx/_static/flecsolve.svg new file mode 100644 index 0000000..e862674 --- /dev/null +++ b/doc/sphinx/_static/flecsolve.svg @@ -0,0 +1,88 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + f + + + + + + + + + v + + + + flecsolve + + + L(v) = f + + diff --git a/doc/sphinx/build.rst b/doc/sphinx/build.rst new file mode 100644 index 0000000..5a70406 --- /dev/null +++ b/doc/sphinx/build.rst @@ -0,0 +1,86 @@ +Build and Install +================= + +flecsolve is a CMake project that requires a C++17 compiler, FleCSI, and +Eigen. AMP support is enabled by default and requires AMP and its TPLs. + +Dependencies +------------ + +Required dependencies: + +* CMake 3.23 or newer +* C++17 compiler +* FleCSI +* Eigen3 + +Optional dependencies: + +* AMP, enabled with ``FLECSOLVE_ENABLE_AMP`` +* TPLs required by AMP + +Configure +--------- + +Configure a release build with AMP enabled: + +.. code-block:: console + + cmake -S . -B build \ + -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_INSTALL_PREFIX=/path/to/install + +Disable AMP support when the AMP-backed wrappers are not needed: + +.. code-block:: console + + cmake -S . -B build \ + -DFLECSOLVE_ENABLE_AMP=OFF + +Build and Test +-------------- + +Build the library: + +.. code-block:: console + + cmake --build build + +Enable and run unit tests: + +.. code-block:: console + + cmake -S . -B build -DFLECSOLVE_ENABLE_UNIT_TESTS=ON + cmake --build build + ctest --test-dir build + +Build examples: + +.. code-block:: console + + cmake -S . -B build -DFLECSOLVE_BUILD_EXAMPLES=ON + cmake --build build + +Install +------- + +Install the library, headers, and CMake package files: + +.. code-block:: console + + cmake --install build + +Downstream CMake projects can then use: + +.. code-block:: cmake + + find_package(flecsolve REQUIRED) + target_link_libraries(my_target PRIVATE flecsolve::flecsolve) + +Spack +----- + +The repository includes Spack package definitions under ``spack-repo``. +The v2 package currently tracks the ``main`` branch and depends on +FleCSI 2.4 or newer, AMP with Hypre and shared libraries, Stacktrace, +and Eigen. diff --git a/doc/sphinx/components.rst b/doc/sphinx/components.rst new file mode 100644 index 0000000..17d2a6f --- /dev/null +++ b/doc/sphinx/components.rst @@ -0,0 +1,409 @@ +Library Components +================== + +flecsolve is organized as a set of composable numerical components +rather than as one application framework. + +Most applications begin with a physical state stored in FleCSI fields. The +vector layer presents that state to numerical algorithms without requiring +the algorithms to know how the fields are distributed. Operators then define +the physics or algebraic action on those vectors. A matrix, a FleCSI task, or +another application-defined implementation can provide that action as long +as it follows the operator interface. + +Solvers and time integrators are consumers of these shared interfaces. A +solver uses an operator to compute residuals and iteratively improve a +solution to a linear or nonlinear problem. A time integrator uses an +operator as the right-hand side of an evolution equation and manages the +work vectors, time-step selection, and (for implicit methods) the linear +solve required at each step. This separation lets one operator be reused in +different algorithms and lets the same algorithm work with different vector +backends. + +The sections below are organized from lower-level data representation to +higher-level algorithms. Read the vector and operator sections first when +adding a new FleCSI application; then choose a matrix, solver, or time +integrator based on the mathematical form of the problem. The final physics +section describes optional higher-level helpers that combine these building +blocks for common discretizations. + +The source paths in this page are relative to the repository root. The +headers are the most precise reference for template signatures and +defaults; this page focuses on the design and the normal usage +patterns. + +Vectors +------- + +Vectors provide the common data model consumed by operators, solvers, and +time integrators. A vector has three parts: + +``Data`` + Describes where values live and how they are accessed. + +``Operations`` + Implements copies, algebraic updates, reductions, and norms for that data. + +``Config`` + Supplies scalar and index types and identifies the physics variable. + +The common implementation is ``flecsolve::vec::core`` in +``flecsolve/vectors/core.hh``. It exposes operations including +``copy``, ``zero``, ``set_scalar``, ``scale``, ``axpy``, ``linear_sum``, +``dot``, ``l2norm``, ``inf_norm``, and ``global_size``. Algorithms use these +operations instead of assuming a particular storage type. + +FleCSI topology views +~~~~~~~~~~~~~~~~~~~~~ + +``flecsolve::vec::topo_view`` adapts a FleCSI field reference to the vector +interface. Construct one with ``flecsolve::vec::make`` after its topology has +been allocated: + +.. code-block:: cpp + + auto solution = flecsolve::vec::make(solution_field(mesh)); + auto work = flecsolve::vec::make(work_field(mesh)); + +The view retains the topology and field references needed to launch the +distributed vector operations. This is the normal choice for FleCSI +applications. The heat-equation tutorial demonstrates this pattern with two +fields representing the current and next solution. + +The view's variable tag can also be used to select a component from a +multi-component vector. A variable is a compile-time label, not a runtime +string; see ``flecsolve/vectors/variable.hh`` and +``flecsolve/vectors/topo_view.hh``. + +Other vector backends +~~~~~~~~~~~~~~~~~~~~~ + +The repository provides several backends: + +* ``flecsolve::vec::multi`` groups component vectors into one vector-like + object. Operators can select the subset of variables they own. +* ``flecsolve::vec::seq`` provides sequential views over contiguous data, + and is useful inside local sparse-matrix kernels. + +Use ``vec::multi`` when a coupled state contains several fields but an +operator acts on only some of them. Use a backend that matches the ownership +and communication model of the underlying data; converting every field to a +new contiguous array usually defeats the purpose of topology-backed vectors. + +Operators +--------- + +An operator maps a domain vector to a range vector. Its essential operation +is: + +.. code-block:: cpp + + template + void apply(const Domain & x, Range & y) const; + +``flecsolve::op::base`` stores optional parameters and declares input and +output variable tags. ``flecsolve::op::core`` adds the vector-facing +``apply``, ``operator()``, and ``residual`` functions. The core wrapper +selects the operator's input and output subsets before forwarding to the +implementation. + +A task-backed operator commonly looks like this: + +.. code-block:: cpp + + struct diffusion : flecsolve::op::base { + using flecsolve::op::base::base; + + template + void apply(const Domain & x, Range & y) const { + flecsi::execute(y.data.topo(), params, y.data.ref(), + x.data.ref()); + } + }; + + flecsolve::op::core F(coefficients); + +The exact task signature depends on the topology and privileges. The +heat-equation operator in ``examples/heat_equation/heat.hh`` is a complete +example of this pattern. + +Operator ownership +~~~~~~~~~~~~~~~~~~ + +Use the handle that matches the lifetime relationship between the algorithm +and the operator: + +``op::ref(F)`` + A non-owning mutable reference. Use this when ``F`` is owned by the caller + and outlives the solver or integrator. + +``op::cref(F)`` + A non-owning const reference. + +``op::make_shared(...)`` + A shared owning handle. This is useful when a solver factory or an + implicit integrator must retain an operator beyond the local scope. + +Handles are defined in ``flecsolve/operators/handle.hh``. Making ownership +explicit avoids accidental copies of large operator state and makes it clear +which objects must remain alive during a solve. + +Shell and composed operators +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``flecsolve/operators/shell.hh`` provides a shell operator for wrapping an +application callback. ``operators/factory.hh`` and +``solvers/factory.hh`` provide runtime selection when an operator or solver +must be chosen from configuration rather than a C++ template parameter. + +Matrices +-------- + +Matrices implement the same operator interface through sparse matrix-vector +multiplication. The base ``flecsolve::mat::sparse`` class delegates its +``apply`` and ``mult`` operations to a backend-specific ``spmv`` operation. +This allows a matrix to be passed anywhere an operator is expected: + +.. code-block:: cpp + + matrix.apply(x, y); // y = A x + matrix.mult(x, y); // equivalent sparse matrix-vector product + +Sequential sparse matrices +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``flecsolve/matrices/seq.hh`` contains compressed and coordinate formats. +The main types are: + +* ``flecsolve::mat::csr`` for compressed sparse row storage; +* ``flecsolve::mat::coo`` for coordinate construction before conversion. + +The compressed representation stores offsets, indices, and values. Use COO +when assembling entries is more convenient, then convert to CSR or CSC for +repeated products. The sequential matrix tests in +``flecsolve/matrices/test`` show the supported construction and serialization +helpers. + +Distributed CSR +~~~~~~~~~~~~~~~ + +``flecsolve::mat::parcsr`` in ``flecsolve/matrices/parcsr.hh`` distributes +the rows and columns of a CSR matrix across MPI processes. Its SpMV is split +into local and remote contributions; the remote part is accumulated in a +temporary topology-backed vector. A parallel CSR matrix can be constructed +from a Matrix Market file or from a distributed CSR initialization object. + +Use ``parcsr`` when the linear system is naturally represented as a sparse +matrix and the matrix is reused across many products. Use a task-backed +operator instead when assembling a matrix would be expensive or when the +physics operator is better evaluated matrix-free. + +Solvers +------- + +The solver package treats a linear system as an operator ``A`` and solves + +.. math:: + + A x = b. + +The Krylov solvers share a common setup: + +1. Create or read solver settings. +2. Allocate work vectors with the solver's ``make_work`` helper. +3. Construct the solver with the operator and optional preconditioner. +4. Call ``apply(b, x)`` and inspect the returned ``solve_info``. + +The available Krylov methods are: + +``cg`` + Conjugate gradient for symmetric positive-definite systems. + +``gmres`` + Generalized minimum residual for nonsymmetric systems. Its work and + restart choices should be considered for large problems. + +``bicgstab`` + A nonsymmetric method with a smaller work footprint than unrestarted + GMRES. + +``nka`` + Nonlinear Krylov acceleration for fixed-point-like updates. + +The solver headers are ``flecsolve/solvers/cg.hh``, ``gmres.hh``, +``bicgstab.hh``, and ``nka.hh``. The runtime registry and factory are in +``flecsolve/solvers/factory.hh``. + +Settings and preconditioning +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Common settings include ``maxiter``, ``rtol``, ``atol``, and +``use_zero_guess``. A preconditioner is another operator with an ``apply`` +method. The solver applies it to residuals without needing to know how the +preconditioner stores data. + +Solver factories and runtime configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When the solver type is known at compile time, construct the solver directly +and use the method-specific ``options`` type. When the solver should be +selected from an input file, use ``flecsolve::krylov_factory`` from +``flecsolve/solvers/factory.hh``. The factory registers the supported Krylov +targets and stores the selected solver settings in a type-safe variant. + +The factory currently supports ``cg``, ``gmres``, ``bicgstab``, and ``nka``. +Its configuration has two levels: ``type`` selects the solver, and the +``[linear-solver.options]`` section supplies the settings for that solver: + +.. code-block:: ini + + [linear-solver] + type = cg + [linear-solver.options] + maxiter = 1000 + rtol = 1e-6 + atol = 1e-8 + use-zero-guess = false + +The corresponding C++ setup reads the factory options and passes the vector +and operator needed to construct the selected solver: + +.. code-block:: cpp + + auto solver_settings = flecsolve::read_config( + "solver.cfg", flecsolve::krylov_factory::options("linear-solver")); + + auto solver = flecsolve::krylov_factory::make_shared( + solver_settings, rhs, A); + +The ``rhs`` argument is used to deduce and allocate the solver's work-vector +type. ``A`` is the operator to invert. ``make_shared`` returns a shared +operator handle, so it can be passed to another component, such as an +implicit time integrator, without exposing which concrete Krylov solver was +selected. Use ``krylov_factory::make`` instead when the resulting value can +remain local and does not need shared ownership. + +The factory's options object must be read together with the configuration +file that contains its sections. The nested options section is important: +``[linear-solver.options]`` is generated from the selected solver's own +options type. Changing ``type`` from ``cg`` to ``gmres`` therefore changes +which options are validated and how the solver is constructed, while the +call site remains unchanged. The factory example in +``flecsolve/solvers/test/nka-factory.cfg`` demonstrates this pattern in a +larger nonlinear solve. + +For a directly constructed solver, the pattern is: + +.. code-block:: cpp + + auto work = flecsolve::op::cg::make_work(u); + flecsolve::op::cg::parameters parameters(settings, op::ref(A), + op::ref(P), work); + flecsolve::op::cg::solver solver(parameters); + auto info = solver.apply(rhs, solution); + +The exact parameter constructor can vary by solver. For configuration-driven +applications, prefer ``krylov_factory`` and the common settings/options +interfaces shown in the heat-equation and solver test examples. + +Always check ``solve_info``. A returned solution may be useful even when the +solver reaches its iteration limit, but the caller should decide whether to +accept it based on ``status``, ``iters``, and the final residual norm. + +Multigrid and AMP integrations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``solvers/mg`` directory contains reusable multigrid building blocks: +levels, coarsening, intergrid transfer, smoothers, and cycles. These pieces +are intended for applications that can provide the corresponding hierarchy +and operators. + +AMP-backed solvers live in ``solvers/amp.hh`` and ``solvers/amp.cc`` and are +enabled by the project's AMP configuration. They are optional; applications +that do not need them can disable AMP as described in the build guide. + +Time integrators +---------------- + +Time integrators solve an evolution equation of the form + +.. math:: + + \frac{d u}{d t} = F(u,t) + +by repeatedly calling an operator ``F``. They own their algorithmic work +vectors but operate on the caller's vector type. + +Explicit Runge--Kutta +~~~~~~~~~~~~~~~~~~~~~ + +``flecsolve/time-integrators/rk23.hh`` implements an adaptive explicit +Runge--Kutta method with an error estimate. ``rk45.hh`` provides a higher +order alternative. The normal loop is: + +.. code-block:: cpp + + integrator.advance(dt, current, next); + bool accepted = integrator.check_solution(); + if (accepted) { + integrator.update(); + std::swap(current, next); + } + dt = integrator.get_next_dt(accepted); + +The integrator may reject a step. Do not swap the solution vectors or advance +application state until ``check_solution`` returns true. + +Implicit BDF +~~~~~~~~~~~~ + +``flecsolve/time-integrators/bdf.hh`` implements variable-step backward +differentiation formulas, including backward Euler, Crank--Nicolson, and +BDF2 through BDF6 modes. Each implicit step requires a linear solve, so the +integrator receives a solver as part of its parameters. + +``operator_adapter`` in ``time-integrators/operator_adapter.hh`` wraps a +right-hand-side operator ``F`` and exposes the scaled implicit operator + +.. math:: + + G(x) = x - \gamma F(x). + +The BDF integrator updates ``gamma`` as the time step changes. This lets the +same physics operator be reused while the linear solver sees the system +appropriate for the current step. + +Configuration +~~~~~~~~~~~~~ + +``flecsolve::util::read_config`` reads Boost program-options settings from a +configuration file. Integrator options are grouped in a named section such +as ``[time-integrator]``; implicit solves commonly add a ``[linear-solver]`` +section. The example files are: + +* ``examples/heat_equation/explicit.cfg`` +* ``examples/heat_equation/implicit.cfg`` +* ``flecsolve/time-integrators/test/explicit.cfg`` +* ``flecsolve/time-integrators/test/implicit.cfg`` + +Physics helpers +--------------- + +The ``flecsolve/physics`` tree builds higher-level pieces from the same +vector and operator abstractions: + +``physics/boundary`` + Dirichlet, Neumann, and Robin boundary-condition interfaces. + +``physics/volume_diffusion`` + Coefficient and diffusion operators for volume-based discretizations. + +``physics/reaction`` + Reaction-rate and mechanism helpers, including Arrhenius and FKN models. + +``physics/specializations`` + FleCSI topology specializations such as finite-volume ``narray`` support. + +These components are useful when the application's discretization matches +their assumptions. Otherwise, implement a small application-specific +operator and retain the generic solver and time-integrator layers. diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py new file mode 100644 index 0000000..b7d8c8a --- /dev/null +++ b/doc/sphinx/conf.py @@ -0,0 +1,41 @@ +# © 2026. Triad National Security, LLC. All rights reserved. +# This program was produced under U.S. Government contract 89233218CNA000001 +# for Los Alamos National Laboratory (LANL), which is operated by Triad +# National Security, LLC for the U.S. Department of Energy/National Nuclear +# Security Administration. All rights in the program are reserved by Triad +# National Security, LLC, and the U.S. Department of Energy/National Nuclear +# Security Administration. The Government is granted for itself and others +# acting on its behalf a nonexclusive, paid-up, irrevocable worldwide license +# in this material to reproduce, prepare derivative works, distribute copies to +# the public, perform publicly and display publicly, and to permit others to do +# so. + +project = "flecsolve" +copyright = "2026, Triad National Security, LLC. All rights reserved." +author = "Los Alamos National Laboratory" + +version = "0.0.1" +release = "0.0.1" + +extensions = [ + "sphinx.ext.githubpages", +] + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +source_suffix = { + ".rst": "restructuredtext", +} +master_doc = "index" +language = "en" + +pygments_style = "sphinx" +nitpicky = True + +html_theme = "furo" +html_static_path = ["_static"] +html_title = "flecsolve documentation" +html_logo = "_static/flecsolve.svg" +html_theme_options = { + "sidebar_hide_name": True, +} diff --git a/doc/sphinx/examples.rst b/doc/sphinx/examples.rst new file mode 100644 index 0000000..6cfb613 --- /dev/null +++ b/doc/sphinx/examples.rst @@ -0,0 +1,45 @@ +Examples +======== + +The repository includes several examples that demonstrate how flecsolve +components are used inside FleCSI applications. + +Heat Equation +------------- + +``examples/heat_equation`` contains explicit and implicit heat-equation +drivers, configuration files, and utilities for generating VTK output +and animations. + +For a guided walkthrough of the problem setup, mesh-backed vectors, +discrete operator, and time integration, see the :doc:`heat-equation-tutorial`. + +Important files: + +* ``examples/heat_equation/explicit.cc`` +* ``examples/heat_equation/implicit.cc`` +* ``examples/heat_equation/heat.hh`` +* ``examples/heat_equation/explicit.cfg`` +* ``examples/heat_equation/implicit.cfg`` + +Poisson +------- + +``examples/poisson`` contains a Poisson example with mesh, control, and +configuration support. + +Equilibrium Diffusion +--------------------- + +``examples/equilibrium_diffusion`` provides a small diffusion example +with source under ``src`` and public headers under ``include``. + +Building Examples +----------------- + +Enable examples at configure time: + +.. code-block:: console + + cmake -S . -B build -DFLECSOLVE_BUILD_EXAMPLES=ON + cmake --build build diff --git a/doc/sphinx/heat-equation-tutorial.rst b/doc/sphinx/heat-equation-tutorial.rst new file mode 100644 index 0000000..142dc66 --- /dev/null +++ b/doc/sphinx/heat-equation-tutorial.rst @@ -0,0 +1,161 @@ +Heat Equation Tutorial +====================== + +This tutorial walks through the two-dimensional heat-equation example in +``examples/heat_equation``. It shows how a FleCSI mesh and fields become +flecsolve vectors, how the discrete Laplacian is exposed as an operator, +and how explicit and implicit time integrators use that operator. + +The complete, buildable source for this tutorial is in the repository under +``examples/heat_equation``. The snippets below are included directly from +that source so that the tutorial stays aligned with the example. + +Problem +------- + +The example solves the heat equation + +.. math:: + + \frac{\partial u}{\partial t} = \alpha \Delta u + \quad \text{in } \Omega = (0,10) \times (0,10), + +with homogeneous Dirichlet boundary conditions and a hot square as the +initial condition: + +.. math:: + + u = 0 \text{ on } \partial\Omega, \qquad + u(x,y,0) = \begin{cases} + 50 & 4 \leq x \leq 6,\ 4 \leq y \leq 6, \\ + 0 & \text{otherwise.} + \end{cases} + +The mesh is distributed across flecsi colors. The command-line mesh +extents specify the number of points in the ``x`` and ``y`` +directions. + +Build the example +----------------- + +Configure the project with examples enabled and build it: + +.. code-block:: console + + cmake -S . -B build -DFLECSOLVE_BUILD_EXAMPLES=ON + cmake --build build + +The executables and their configuration files are written to +``build/examples/heat_equation``. + +Run the example +--------------- + +Run the explicit RK23 version on four MPI processes: + +.. code-block:: console + + cd build/examples/heat_equation + mpirun -np 4 ./heat-explicit 100 100 -d 1.5 -o true + +Run the implicit BDF version with the same mesh and diffusivity: + +.. code-block:: console + + mpirun -np 4 ./heat-implicit 100 100 -d 1.5 -o true + +The positional arguments are the ``x`` and ``y`` mesh extents. The ``-d`` +option sets the diffusivity ``alpha`` and ``-o true`` writes every accepted +time step. The ``explicit.cfg`` and ``implicit.cfg`` files control the time +integrator and linear-solver settings. + +The final output is written by the ``finalize`` control point. With +``-o true``, intermediate files are also written using names such as +``timestep-0-0.dat``. The files contain ``x``, ``y``, and ``u`` columns and +can be visualized with the utilities in ``examples/heat_equation/util``. + +Mesh and vectors +---------------- + +The example specializes FleCSI's ``narray`` topology as a two-dimensional +mesh. Two fields hold the current and next solution values. The control +policy turns those fields into flecsolve topology views after the mesh has +been allocated: + +.. literalinclude:: ../../examples/heat_equation/control.hh + :language: cpp + :lines: 39-66 + +The topology and field definitions are in +``examples/heat_equation/mesh.hh``. A topology view lets the time integrator +operate on FleCSI fields through the standard flecsolve vector interface. + +Initial and boundary conditions +------------------------------- + +The ``initialize`` control point first allocates the mesh and then launches +the ``ics`` task. That task sets the value to ``50`` inside the square +``[4, 6] x [4, 6]`` and to zero elsewhere. The implementation is in +``examples/heat_equation/heat.cc``. + +The discrete Laplacian applies the zero Dirichlet boundary condition before +computing interior values. The boundary checks account for MPI subdomains, +so only processes that own a global boundary write those boundary values. + +Discrete operator +----------------- + +The ``laplace`` task uses the mesh spacing and a centered finite-difference +stencil. It computes ``alpha * Laplacian(u)`` into the output vector: + +.. literalinclude:: ../../examples/heat_equation/heat.hh + :language: cpp + :lines: 65-115 + +The task is wrapped in ``heat_op``, which implements the flecsolve operator +interface. Its ``apply`` method launches the task with the topology and +field references obtained from the input and output vectors: + +.. literalinclude:: ../../examples/heat_equation/heat.hh + :language: cpp + :lines: 119-131 + +Explicit integration +-------------------- + +The explicit driver constructs an RK23 integrator using the heat operator, +the settings read from ``explicit.cfg``, and work vectors created from the +solution vector: + +.. literalinclude:: ../../examples/heat_equation/explicit.cc + :language: cpp + :lines: 8-51 + +At each iteration, ``advance`` proposes a new solution. The driver checks +the result, updates the integrator state, swaps the current and next vectors, +and asks the integrator for the next time step. + +Implicit integration +-------------------- + +The implicit driver uses BDF and a Krylov solver. An ``operator_adapter`` +turns the heat operator ``F = alpha Laplacian`` into the operator required by +the implicit method, such as ``I - gamma F``. The solver factory selects the +linear solver from ``implicit.cfg``: + +.. literalinclude:: ../../examples/heat_equation/implicit.cc + :language: cpp + :lines: 8-57 + +Next steps +---------- + +To experiment with the example, try changing the following: + +* Set ``diffusivity`` with ``-d`` to change the rate of diffusion. +* Change ``initial-dt``, ``max-dt``, or the final time in the configuration + files. +* Increase the mesh extents to study spatial resolution and parallel scaling. +* Modify ``task::ics`` in ``heat.cc`` to use a different initial condition. +* Modify ``task::laplace`` in ``heat.hh`` to experiment with another stencil + or boundary condition. diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst new file mode 100644 index 0000000..7443d65 --- /dev/null +++ b/doc/sphinx/index.rst @@ -0,0 +1,61 @@ +flecsolve Documentation +======================= + +flecsolve is a parallel computational framework for multi-physics +application development using the open source `FleCSI +`_ programming system. It provides a +linear algebra interface to FleCSI data abstractions and uses that +interface to implement reusable vectors, operators, matrices, time +integrators, and solvers for FleCSI applications. + +The project follows design principles from the `AMP +`_ package while keeping the +core solver interfaces lightweight and composable for FleCSI-based +applications. + +Library Structure +----------------- + +**Vectors** + Core vector interfaces and implementations for FleCSI topology-backed + fields, multi-component vectors, and PETSc-backed vectors. + +**Operators** + Interfaces for maps between vector spaces, including ownership-aware + operator handles used by solvers and time integrators. + +**Matrices** + Sequential sparse matrix types and a parallel compressed sparse row + matrix implementation. + +**Solvers** + Krylov solvers, nonlinear acceleration utilities, and multigrid + components. + +**Time Integrators** + Variable-step explicit and implicit integrators that operate on the + flecsolve vector and operator abstractions. + +Release +------- + +This software has been approved for open source release and has been +assigned **O4869**. + +License +------- + +flecsolve is open source under the BSD-3-Clause license. See the +repository ``LICENSE`` file for the complete terms. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + overview + build + user-guide + components + examples + heat-equation-tutorial + release-notes diff --git a/doc/sphinx/overview.rst b/doc/sphinx/overview.rst new file mode 100644 index 0000000..e2c8f40 --- /dev/null +++ b/doc/sphinx/overview.rst @@ -0,0 +1,83 @@ +Overview +======== + +flecsolve provides reusable numerical building blocks for applications +that already use FleCSI for data, execution, and control flow. The main +interfaces are intentionally generic: solvers and time integrators work +with any vector type that provides the expected vector operations, and +operators define mappings through an ``apply`` interface. + +Vectors +------- + +The core vector type is built from three pieces: + +**Data** + Storage and access to the underlying values. + +**Operations** + Common linear algebra operations such as copy, scaling, vector sums, + dot products, and norms. + +**Variable** + A static tag that identifies the physics field represented by the + vector. + +The ``flecsolve::vec::topo_view`` adapter maps fields on a FleCSI +topology to the vector interface. The ``flecsolve::vec::multi`` type +groups component vectors so physics packages can pass coupled state +through one vector-like object while allowing operators to select the +subset they own. + +Operators +--------- + +Operators define maps from a domain vector to a range vector. A user +operator implements the desired map in an ``apply`` function, typically +by launching FleCSI tasks or by composing existing vector operations. + +Operator handles make ownership explicit: + +**Shared handles** + Use ``flecsolve::op::make_shared`` to create a shared owning handle. + +**Mutable references** + Use ``flecsolve::op::ref`` to create a non-owning mutable reference + handle. + +**Const references** + Use ``flecsolve::op::cref`` to create a non-owning const reference + handle. + +Solvers +------- + +The solver components include conjugate gradient, BiCGSTAB, GMRES, +nonlinear Krylov acceleration, AMP-backed solvers, and multigrid pieces. +Krylov solver namespaces follow a common structure: + +**Settings** + Runtime configuration such as tolerances and iteration limits. + +**Options** + Boost program-options definitions used to populate settings from a + configuration file. + +**Work-vector factories** + Factories used to allocate all vectors required during a solve before + the solve begins. + +**Solver object** + The entry point that binds an operator, optional preconditioner, and + optional diagnostic callback into an approximate inverse operator. + +The corresponding identifiers are generally named ``settings``, +``options``, ``make_work``, and ``solver`` in each solver namespace. + +Time Integrators +---------------- + +The time integration package includes adaptive explicit Runge-Kutta +methods and implicit BDF support. Like the solvers, these integrators are +implemented against the vector and operator interfaces so they can be +used with application-specific FleCSI topology and field types. diff --git a/doc/sphinx/release-notes.rst b/doc/sphinx/release-notes.rst new file mode 100644 index 0000000..dcc1743 --- /dev/null +++ b/doc/sphinx/release-notes.rst @@ -0,0 +1,24 @@ +Release Notes +============= + +1.0.0 +----- + +Initial release. + +Added +~~~~~ + +* FleCSI-backed vector interface adapters and multi-component vector + support. +* Operator interfaces and ownership-aware operator handles. +* Sequential and parallel CSR matrix support. +* Krylov solver components including conjugate gradient, BiCGSTAB, + GMRES, and nonlinear Krylov acceleration. +* Multigrid components and AMP-backed solver wrappers. +* Explicit and implicit time integration components. +* Example applications for heat equation, Poisson, and equilibrium + diffusion workflows. +* Spack package definitions for flecsolve. +* Initial Sphinx documentation and documentation build workflow for + GitHub Pages publishing. diff --git a/doc/sphinx/user-guide.rst b/doc/sphinx/user-guide.rst new file mode 100644 index 0000000..ceafe7a --- /dev/null +++ b/doc/sphinx/user-guide.rst @@ -0,0 +1,63 @@ +User Guide +========== + +This guide summarizes the main programming concepts used by flecsolve. +The interfaces are C++ templates, so application code normally includes +the relevant headers and lets solver, vector, and operator types be +deduced from the concrete FleCSI fields and topology views passed in. + +The :doc:`components` guide provides a detailed tour of the vector, +operator, matrix, solver, time-integrator, and physics layers. This page +collects the cross-cutting patterns that are most important when assembling +an application. + +Vector Interface +---------------- + +flecsolve algorithms expect vector-like objects that provide common +linear algebra operations. For FleCSI applications, ``vec::topo_view`` is +the primary adapter from FleCSI fields and topologies into that vector +interface. + +Multi-component physics state can be represented with ``vec::multi``. +This is useful when different operators own different physics variables +but a solver or time integrator needs to carry the coupled state as one +object. + +Operator Interface +------------------ + +An operator maps a domain vector to a range vector by implementing an +``apply`` operation. The concrete map may launch FleCSI tasks, call into +matrix kernels, or compose lower-level vector operations. + +When passing operators to solvers or time integrators, use operator +handles to make ownership explicit. Shared ownership uses +``op::make_shared``; non-owning references use ``op::ref`` or +``op::cref``. + +Krylov Diagnostics +------------------ + +Krylov solvers can accept an optional diagnostic callback. The callback +can monitor convergence and request early termination. + +.. code-block:: cpp + + bool diagnostic(const Vector & current_solution, double residual_norm); + +The callback returns ``true`` when the solve should stop early. + +Configuration Files +------------------- + +Many solver and time-integrator settings are exposed through Boost +program-options wrappers. Existing tests and examples include ``.cfg`` +files that show the expected option names and values. + +Useful starting points in the repository: + +* ``flecsolve/solvers/test/*.cfg`` +* ``flecsolve/time-integrators/test/*.cfg`` +* ``examples/heat_equation/*.cfg`` +* ``examples/poisson/poisson.cfg``