Interfaces#

This module groups procedures behind interfaces in all the common ways:

solve is a generic interface over module procedures (module procedure),
norm declares interface bodies whose implementation lives in a submodule,
operator(.dot.) defines a user operator,
residual_callback is an abstract interface.

Each interface lists the specific procedures it groups under Procedures. Specifics that are private to the module are still documented, since they are reachable through the public interface.

example_06.f90#

!> Linear solvers showcasing the different flavours of interfaces.

module linear_solvers
  implicit none
  private

  public :: solve, norm, residual_callback, operator(.dot.)

  !> Solve the linear system :math:`A x = b` for any supported kind.
  !>
  !> The specific procedure is selected at compile time from the type of
  !> the arguments.
  interface solve
    module procedure solve_real, solve_complex
  end interface solve

  !> Vector norms, implemented in a submodule.
  interface norm
    !> Euclidean norm :math:`\|x\|_2`.
    pure module function norm_2(x) result(res)
      real, intent(in) :: x(:) !> Input vector
      real :: res !> Euclidean norm of ``x``
    end function norm_2
    !> Norm of order ``p``.
    pure module function norm_p(x, p) result(res)
      real, intent(in) :: x(:) !> Input vector
      integer, intent(in) :: p !> Order of the norm
      real :: res !> ``p``-norm of ``x``
    end function norm_p
  end interface norm

  !> Dot product operator: ``a .dot. b``.
  interface operator(.dot.)
    module procedure dot_real
  end interface operator(.dot.)

  abstract interface
    !> Signature of a user-supplied residual monitor, called once per iteration.
    subroutine residual_callback(iter, residual)
      integer, intent(in) :: iter !> Iteration number
      real, intent(in) :: residual !> Current residual norm
    end subroutine residual_callback
  end interface

contains

  !> Solve a real-valued system in place.
  subroutine solve_real(a, b)
    real, intent(in) :: a(:, :) !> System matrix
    real, intent(inout) :: b(:) !> Right-hand side, overwritten with the solution
  end subroutine solve_real

  !> Solve a complex-valued system in place.
  subroutine solve_complex(a, b)
    complex, intent(in) :: a(:, :) !> System matrix
    complex, intent(inout) :: b(:) !> Right-hand side, overwritten with the solution
  end subroutine solve_complex

  !> Dot product of two real vectors.
  pure function dot_real(a, b) result(res)
    real, intent(in) :: a(:) !> First vector
    real, intent(in) :: b(:) !> Second vector
    real :: res !> Dot product
    res = sum(a * b)
  end function dot_real

end module linear_solvers

linear_solvers (module)#

Linear solvers showcasing the different flavours of interfaces.

Interfaces

solve (interface)#

solve (interface)

Solve the linear system \(A x = b\) for any supported kind.

The specific procedure is selected at compile time from the type of the arguments.

Procedures:

solve_real
solve_complex

norm (interface)#

norm (interface)

Vector norms, implemented in a submodule.

Procedures:

norm_2
norm_p

pure module function norm_2(x) -> res#

Euclidean norm \(\|x\|_2\).

Arguments:

xreal, intent(in), dimension(:): Input vector

Returns:

resreal: Euclidean norm of x

pure module function norm_p(x, p) -> res#

Norm of order p.

Arguments:

xreal, intent(in), dimension(:): Input vector
pinteger, intent(in): Order of the norm

Returns:

resreal: p-norm of x

operator(.dot.) (interface)#

operator(.dot.) (interface)

Dot product operator: a .dot. b.

Procedures:

dot_real

residual_callback (interface)#

subroutine residual_callback(iter, residual)

Signature of a user-supplied residual monitor, called once per iteration.

Arguments:

iterinteger, intent(in): Iteration number
residualreal, intent(in): Current residual norm

Procedures

solve_real (subroutine)#

subroutine solve_real(a, b)

Solve a real-valued system in place.

Arguments:

areal, intent(in), dimension(:, :): System matrix
breal, intent(inout), dimension(:): Right-hand side, overwritten with the solution

solve_complex (subroutine)#

subroutine solve_complex(a, b)

Solve a complex-valued system in place.

Arguments:

acomplex, intent(in), dimension(:, :): System matrix
bcomplex, intent(inout), dimension(:): Right-hand side, overwritten with the solution

dot_real (function)#

pure function dot_real(a, b) -> res

Dot product of two real vectors.

Arguments:

areal, intent(in), dimension(:): First vector
breal, intent(in), dimension(:): Second vector

Returns:

resreal: Dot product

Declaring an interface by hand#

The f:interface directive lists the specific procedures of the interface of the same name in fortran_sources by default, so nothing needs to be repeated. The :module: option picks the module (or submodule) to look in when several of them define an interface with that name:

.. f:interface:: trapz
    :module: stdlib_quadrature

    Integrates sampled values using the trapezoidal rule.

which renders as:

trapz#

Integrates sampled values using the trapezoidal rule.

Procedures:

trapz_dx_dp
trapz_x_dp

Here trapz comes from example_04_parent_module.f90. Its specifics are not documented on any page, so they are listed without links.

The :procedures: option overrides that list, for instance to keep only some of the specifics or to document an interface that is not parsed at all. Names that the parsed interface does not contain are reported as warnings. Each name links to its documentation, whether parsed or declared by hand:

.. f:interface:: interpolate
    :procedures: interp_linear, interp_cubic

    Interpolate tabulated data at new abscissae.

.. f:function:: interp_linear

    Piecewise-linear interpolation.

.. f:function:: interp_cubic

    Cubic spline interpolation.

which renders as:

interpolate#

Interpolate tabulated data at new abscissae.

Procedures:

interp_linear
interp_cubic

interp_linear#: Piecewise-linear interpolation.

interp_cubic#: Cubic spline interpolation.