From 2d4d5b3df0d8ca142b9203abe404b03c4f3a8f63 Mon Sep 17 00:00:00 2001 From: David Ketcheson Date: Sat, 28 Sep 2024 12:40:19 +0300 Subject: [PATCH] Improvements to PyClaw solvers page. Move reference documentation to a separate page. Remove or reword some unclear/irrelevant/incorrect statements and examples. --- doc/pyclaw/solvers.rst | 89 +++++++------------------------- doc/pyclaw/solvers_reference.rst | 20 +++++++ 2 files changed, 40 insertions(+), 69 deletions(-) create mode 100644 doc/pyclaw/solvers_reference.rst diff --git a/doc/pyclaw/solvers.rst b/doc/pyclaw/solvers.rst index 9228abc..730a9c3 100644 --- a/doc/pyclaw/solvers.rst +++ b/doc/pyclaw/solvers.rst @@ -10,7 +10,7 @@ Using PyClaw's solvers: Classic and SharpClaw At present, PyClaw includes two types of solvers: - * Classic: the original Clawpack algorithms, in 1/2/3D + * Classic: the original 2nd-order Clawpack algorithms, in 1/2/3D * SharpClaw: higher-order wave propagation using WENO reconstruction and Runge-Kutta integration, in 1/2D @@ -42,9 +42,9 @@ For typical problems involving shocks, the Classic solvers are recommended. For problems involving high-frequency waves, turbulence, or smooth solutions, the SharpClaw solvers may give more accurate solutions at less cost. This is an active area of research and you may wish to experiment with both solvers. - -Future plans include incorporation of finite-difference and discontinuous Galerkin -solvers. +Finally, note that the high-order WENO reconstruction in SharpClaw is +implemented only for uniform Cartesian grids. For mapped grids, it is recommended +to use the Classic solvers or to use SharpClaw with TVD 2nd-order reconstruction. Key differences between the Classic and SharpClaw solvers are: @@ -60,89 +60,40 @@ Key differences between the Classic and SharpClaw solvers are: values, see the documentation of the :class:`~pyclaw.classic.solver.ClawSolver` and :class:`~pyclaw.sharpclaw.solver.SharpClawSolver` classes. +For details of the solvers and their options, see :ref:`solvers_reference`. .. _sharpclaw_solvers: =============================== -SharpClaw Solvers +PyClaw's SharpClaw Solvers =============================== The SharpClaw solvers are a collection of solvers that contain the functionality of the Fortran code SharpClaw, developed in David Ketcheson's -thesis. The 1D SharpClaw solver contains a pure Python implementation as -well as a wrapped Fortran version. The 2D solver is in progress but not -available yet. The SharpClaw solvers provide an interface similar to that +thesis. Solvers are available for 1D and 2D problems. +The SharpClaw solvers provide an interface similar to that of the classic Clawpack solvers, but with a few different options. -The superclass solvers are not meant -to be used separately but are there to provide common routines for all the -Clawpack solvers. Please refer to each of the inherited classes for more info -about the methods and attributes they provide each class. -.. The inheritance structure is: - -.. .. inheritance-diagram:: pyclaw.sharpclaw.solver.SharpClawSolver1D pyclaw.sharpclaw.solver.SharpClawSolver2D - -:Example: - - This is a simple example of how to instantiate and evolve a solution to a - later time :math:`\text{t_end}` using the 1D acoustics Riemann solver. - -.. doctest:: - - >>> from clawpack import pyclaw - >>> solver = pyclaw.SharpClawSolver1D() # Instantiate a default, 1d solver - - >>> solver.evolve_to_time(solution,t_end) # Evolve the solution to t_end # doctest: +SKIP - - -:mod:`pyclaw.sharpclaw` -=============================== - -.. autoclass:: clawpack.pyclaw.sharpclaw.solver.SharpClawSolver - :members: - +The class `clawpack.pyclaw.SharpClawSolver` is a pure virtual class +not meant to be instantiated; you should use +`clawpack.pyclaw.SharpClawSolver1D` or `clawpack.pyclaw.SharpClawSolver2D`. +Most of the examples in `clawpack/pyclaw/examples` show how to use either +Classic or SharpClaw. .. _pyclaw_clawpack_solvers: -=============================== -Pyclaw Classic Clawpack Solvers -=============================== +================================== +Pyclaw's Classic Clawpack Solvers +================================== The pyclaw classic clawpack solvers are a collection of solvers that represent the functionality of the older versions of clawpack. It comes in two forms, a pure python version and a python wrapping of the fortran libraries. All of the solvers available provide the same basic interface and provide the same -options as the old versions of clawpack. The superclass solvers are not meant -to be used separately but there to provide common routines for all the -Clawpack solvers. Please refer to each of the inherited classes for more info -about the methods and attributes they provide each class. -.. The inheritance structure is: - -.. .. inheritance-diagram:: clawpack.pyclaw.classic.solver.ClawSolver1D clawpack.pyclaw.classic.solver.ClawSolver2D clawpack.pyclaw.classic.solver.ClawSolver3D - -:Example: - - This is a simple example of how to instantiate and evolve a solution to a - later time :math:`\text{t_end}` using the linearized 1d acoustics Riemann solver - -.. doctest:: - - >>> from clawpack import pyclaw - >>> solver = pyclaw.ClawSolver1D() # Instantiate a default, 1d solver - >>> solver.limiters = pyclaw.limiters.tvd.vanleer # Use the van Leer limiter - >>> solver.dt = 0.0001 # Set the initial time step - >>> solver.max_steps = 500 # Set the maximum number of time steps - -.. doctest:: - - >>> solver.evolve_to_time(solution,t_end) # Evolve the solution to t_end # doctest: +SKIP - - -:mod:`pyclaw.classic.solver` -============================= - -.. autoclass:: clawpack.pyclaw.classic.solver.ClawSolver - :members: +options as the old versions of clawpack. +The class `clawpack.pyclaw.ClawSolver` is a pure virtual class +not meant to be instantiated; you should use +`clawpack.pyclaw.ClawSolver1D`, `clawpack.pyclaw.ClawSolver2D`, or `clawpack.pyclaw.ClawSolver3D`. .. _pyclaw_clawpack_solvers_custom_BC_change: diff --git a/doc/pyclaw/solvers_reference.rst b/doc/pyclaw/solvers_reference.rst new file mode 100644 index 0000000..93f9454 --- /dev/null +++ b/doc/pyclaw/solvers_reference.rst @@ -0,0 +1,20 @@ +:group: pyclaw + +.. contents:: + +.. _solvers_reference: + +:mod:`pyclaw.classic.solver` +============================= + +.. autoclass:: clawpack.pyclaw.classic.solver.ClawSolver + :members: + + +:mod:`pyclaw.sharpclaw` +=============================== + +.. autoclass:: clawpack.pyclaw.sharpclaw.solver.SharpClawSolver + :members: + +