import sphinx.ext.autodoc .. _fvm:

The 1D finite volume element (fvm) library

The torax.fvm library can be thought of as a distinct submodule of torax that is agnostic to the Tokamak modeling problem. The fvm module abstracts the problem to a coupled set of one dimensional convection-diffusion PDEs with diffusion, convection, implicit and explicit source, and transient terms. In principle, this module could be used to solve other differential equations of this form—all of the calculations of the values of the coefficients to make them describe the tokamak core transport equations are done in other parts of torax.

The fvm module can be thought of as similar in purpose to fipy. Both solve differential equations with the same structure (diffusion, convection etc terms describing fluid dynamics). It is instructive to also compare their differences. fipy is designed to be much more general and to be applied to a wider variety of PDEs and with support for higher dimensions and arbitrary mesh topologies. torax.fvm is much less general —it avoids hard-coded Tokamak physics into torax.fvm but has not attempted to include any more features than needed for the Tokamak transport problem. torax.fvm thus supports only one topology, the 1-D grid topology. However, within this restricted domain, torax.fvm offers a variety of solver techniques not available in fipy, especially solver techniques that are possible only with differentiable solvers, in our case enabled by JAX. For example, in torax.fvm the diffusion etc. coefficients are not raw numerical values, they are JAX expressions, so when solvers like Newton-Raphson take derivatives to form a Jacobian, they can actually differentiate through the diffusion coefficients to form derivatives that are functions of more fundamental underlying physical properties of the Tokamak.

The fvm module can roughly be categorized into three kinds of submodules:

(1) Highly user-facing modules that provide solver functionality: .. comment:: api-doc makes a file for all of torax.fvm, not the

individual submodules, so I can’t make these list entries be links.

  • implicit_solve_block : Linear solver

  • newton_raphson_solve_block : Nonlinear Newton-Raphson solver

  • optimizer_solve_block : Nonlinear optimization-based solver

  1. Moderately user-facing modules that define types. Users of the

fvm module still need to import most of these to construct arguments and write type hints but they are not quite as front and center:

  • block_1d_coeffs

  • cell_variable

  • enums

(3) The remaining files are implementation files that do things like define the residual functions for the Newton method, perform discretization to construct theta method equations, etc.

Categories (1) and (2) are documented adequately from the API reference but category (3) is the result of extensive mathematical derivation and its behavior is strongly affected by several very subtle points. This developer documentation describes in detail how / why the exact current implementation was derived.

Under construction.