Improve Problem classes Documentation

[tlunet]

Currently problem class constructors explicitly define in their signature the problem parameters, for instance :

class acoustic_1d_imex(ptype):
    """
    Example implementing the one-dimensional IMEX acoustic-advection

    TODO : doku
    """

    dtype_u = mesh
    dtype_f = imex_mesh

    def __init__(self, nvars, cs, cadv, order_adv, waveno):
        # ... implementation ...

But only a few of the problem classes have a fully detailed documentation describing the problem parameters (for an example, see the advectionNd class).

When working with a given problem, it would be good to also add in the same time the documentation for its class, following the documentation guidelines.

Note : for the problem class, since parameter are automatically stored as attributes (following the contribution guidelines), it is then not necessary to describe the parameters a second time in the Attributes doc section. For example :

class AdvectionSpectral(ptype):
    r"""
    This class implement the advection problem

    .. math::
        \frac{\partial u}{\partial t} = -c\frac{\partial u}{\partial x},

    on :math:`[0,1]^N` using periodic boundary conditions and spectral Fourier
    discretization to estimate the space derivative term.

    Parameters
    ----------
    nvars : int of tuple, optional
        Spatial resolution (same in all dimensions). Using a tuple allows to
        consider several dimensions, e.g nvars=(16,16) for a 2D problem.
    c : float, optional
        Advection speed (same in all dimensions).

    Attributes
    ----------
    A : np.ndarray
        Discretization matrix for the :math:`\frac{\partial u}{\partial x}`
        term (dense).
    """

    dtype_u = mesh
    dtype_f = imex_mesh

    def __init__(self, nvars, c):
        super().__init__((nvars, None, np.dtype('float64')))
        self._makeAttributeAndRegister('nvars', 'c', localVars=locals(), readOnly=True)
        self.A = generateSpectralFourierMatrix(nvars)
        self.A += -c

:warning: Note the spaces before and after the semicolon when describing the type of a variable, e.g A : np.ndarray.

In Spyder IDE, this would render like this :

Finally, here is a (non-exhaustive) list of problem classes for which documentation should be reworked or added :

• [x] acoustic_1d_imex
• [x] advectiondiffusion1d_imex
• [x] advectiondiffusion1d_implicit
• [x] allencahn_front_fullyimplicit
• [x] allencahn_front_semiimplicit
• [x] allencahn_periodic_fullyimplicit
• [x] allencahn_periodic_semiimplicit
• [x] allencahn_periodic_multiimplicit (eventually, all the `allencahn class could be merged into a single one ...)
• [x] allencahn_temp_imex
• [x] auzinger
• [x] battery_n_capacitors
• [x] boussinesq_2d_imex
• [x] buck_converter
• [x] swfw_scalar
• [x] fermi_pasta_ulam_tsingou
• [x] full_solar_system
• [x] generalized_fisher
• [x] GenericNDimFinDiff
• [x] grayscott_imex_diffusion
• [x] harmonic_oscillator
• [x] fenics_heat
• [x] fenics_heat_mass
• [x] fenics_heat_weak_fullyimplicit
• [x] fenics_heat_weak_imex
• [x] heat2d_petsc_forced
• [x] heatNd_unforced
• [x] heatNd_forced
• [x] heatNd_forced (CuPy problem class)
• [x] heatNd_unforced (CuPy problem class)
• [x] henon_heiles
• [x] logistics_equation
• [x] LorenzAttractor
• [x] nonlinearschroedinger_imex
• [x] outer_solar_system
• [x] penningtrap
• [x] piline
• [x] Quench
• [x] QuenchIMEX
• [x] testequation0d
• [x] vanderpol
• [x] fenics_vortex_2d
• [x] nonlinear_ODE_1
• [x] ... add here additional classes as soon as they are documented ...

[pancetta]

Hm, are the spaces before the : necessary? English grammar does not have this (neither German), so I really don't want to use that in the code (if not needed for some strange reason).

[tlunet]

Hm, are the spaces before the : necessary?

Yes ! If not, sphinx renders the type in bold font too. This is actually the standard of Numpy Style Docstring, see https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html

PS : French syntax rules ! :smile: