diff --git a/meanas/fdmath/__init__.py b/meanas/fdmath/__init__.py index 97491d9..b6b75d5 100644 --- a/meanas/fdmath/__init__.py +++ b/meanas/fdmath/__init__.py @@ -2,7 +2,34 @@ Basic discrete calculus for finite difference (fd) simulations. -TODO: short description of functional vs operator form + +Fields, Functions, and Operators +================================ + +Discrete fields are stored in one of two forms: + +- The `field_t` form is a multidimensional numpy array + + For a scalar field, this is just `U[m, n, p]`, where `m`, `n`, and `p` are + discrete indices referring to positions on the x, y, and z axes respectively. + + For a vector field, the first index specifies which vector component is accessed: + `E[:, m, n, p] = [Ex[m, n, p], Ey[m, n, p], Ez[m, n, p]]`. +- The `vfield_t` form is simply a vectorzied (i.e. 1D) version of the `field_t`, + as obtained by `meanas.fdmath.vectorization.vec` (effectively just `numpy.ravel`) + +Operators which act on fields also come in two forms: + + Python functions, created by the functions in `meanas.fdmath.functional`. + The generated functions act on fields in the `field_t` form. + + Linear operators, usually 2D sparse matrices using `scipy.sparse`, created + by `meanas.fdmath.operators`. These operators act on vectorized fields in the + `vfield_t` form. + +The operations performed should be equivalent: `functional.op(*args)(E)` should be +equivalent to `unvec(operators.op(*args) @ vec(E), E.shape[1:])`. + +Generally speaking the `field_t` form is easier to work with, but can be harder or less +efficient to compose (e.g. it is easy to generate a single matrix by multiplying a +series of other matrices). + Discrete calculus =================