MOLE: Mimetic Operators Library Enhanced

MOLE is a library that implements high-order mimetic operators to solve partial differential equations. This site provides documentation for the Julia implementation of MOLE. More information can be found on the main documentation site and the GitHub repository.

Getting Started

MOLE.jl is registered in the General Julia registry under the package name MOLE. To install it, start Julia, enter the pkg mode by pressing ], and type

pkg> add MOLE

or, equivalently, from the command line:

julia -e 'using Pkg; Pkg.add("MOLE")'

Once installed, load the library in your scripts or in the REPL with

using MOLE

Using MOLE.jl from source

To run the examples and the test suite, build the documentation, or contribute to MOLE.jl, clone the MOLE repository locally. Then navigate to the location where the repository has been cloned to and go to the mole/julia/MOLE.jl sub-directory. From here, you can access the library via the REPL or the command line.

From the REPL

In mole/julia/MOLE.jl, start Julia using the command julia --project=.. Next, the package library needs to be instantiated and pre-compiled. Enter the pkg mode by pressing ], then type the commands instantiate and precompile (one at a time). This should activate the MOLE.jl package and install the necessary dependencies.

Then, to run a script such as myScript.jl, you can use the following command in the REPL:

include("path/to/myScript.jl")

From the command line

In mole/julia/MOLE.jl, use the following commands to instatiate and precompile the MOLE package:

julia --project=. -e 'using Pkg; Pkg.instantiate()'
julia --project=. -e 'using Pkg; Pkg.precompile()'

Then, to run a script such as myScript.jl, use the command

julia --project=. path/to/myScript.jl

Running the test suite

To run the unit tests, first enter the Julia REPL as in the above section (that is, by running the command julia --project=. from the directory mole/julia/MOLE.jl). Next, enter the pkg mode by pressing ], then type the command test. The results of the unit tests should be displayed to your console.

Building the documentation

MOLE.jl uses Documenter.jl to build its Julia implementation documentation. From the mole/julia/MOLE.jl directory, navigate to the docs/ directory, with

cd docs/

From the REPL

To build the documentation from the docs/ directory, start Julia with the command julia --project=.. You should see the Julia REPL starting with the (docs) environment. Next, enter the pkg mode by pressing ], and then type the commands instantiate and precompile (one at a time). This should activate the docs environment (specific to build the documentation) and install the necessary dependencies.

Then, to build the documentation you can use the following command in the REPL:

include("make.jl")

From the command line

To build the documentation from the docs/ directory, use the following commands to instatiate and precompile the documentation environment:

julia --project=. -e 'using Pkg; Pkg.instantiate()'
julia --project=. -e 'using Pkg; Pkg.precompile()'

Then build the documentation with the command

julia --project=. make.jl

Preview the documentation

Once you have built the documentation (either from the REPL or the command line), you can inspect the documentation in docs/build with the index.html file as the homepage.

Functions

Grids

The Grids module provides the grid data structures. A grid stores dimensionality, topology, spacing, coordinates, and boundary metadata in one object.

Example of usage:

using MOLE.Grids

grid = makeGrid(m=64, n=64, dx=1/64, dy=1/64)

grid.dim
grid.topology
grid.nodes
grid.faces
grid.centers
MOLE.Grids.makeGrid — Function
makeGrid(grid::Grid; allowPartial::Bool = true)
makeGrid(; allowPartial::Bool = true, kwargs...)

Construct and validate a computational grid.

makeGrid is the primary constructor for Grid objects. It accepts either an existing Grid instance or keyword arguments describing the computational domain. The resulting grid is validated, normalized, and enriched with derived metadata such as the spatial dimension, topology, coordinate arrays, and boundary-condition information.

Arguments

  • grid::Grid: An existing grid to validate and normalize.
  • allowPartial::Bool=true: If true, allows partially specified grids to be created without requiring all fields. This is primarily intended for incremental grid construction or internal use.

When called with keyword arguments, commonly used parameters include:

  • m, n, o: Number of cells in each spatial direction.
  • dx, dy, dz: Grid spacing in each spatial direction.
  • topology: Grid topology (e.g. :uniform, :periodic, :curvilinear).
  • nodes: User-supplied nodal coordinates for curvilinear grids.
  • bc: Boundary-condition metadata.

Returns

A validated Grid object.

Examples

Construct a one-dimensional uniform grid:

grid = makeGrid(
    m = 100,
    dx = 0.01,
)

Construct a two-dimensional uniform grid:

grid = makeGrid(
    m = 64,
    n = 64,
    dx = 1/64,
    dy = 1/64,
)

Construct a curvilinear grid from user-defined nodal coordinates:

grid = makeGrid(
    m = m,
    n = n,
    topology = :curvilinear,
    nodes = (X = X, Y = Y),
)

Notes

makeGrid delegates the validation and normalization of all inputs to validateGrid.

source
MOLE.Grids.validateGrid — Function
validateGrid(grid::Grid; allowPartial=false)
validateGrid(raw::AbstractDict{Symbol,<:Any}; allowPartial=false)

Validate and normalize a computational grid.

validateGrid verifies that a grid definition is internally consistent, infers missing metadata when possible, and returns a fully normalized Grid object. Depending on the supplied information, it determines the spatial dimension and grid topology, validates boundary-condition data, and generates the coordinate arrays associated with nodes, faces, and cell centers.

This function is called internally by makeGrid, but may also be used directly to validate existing grid objects or dictionaries containing grid definitions.

Arguments

  • grid::Grid: A grid object to validate and normalize.
  • raw::AbstractDict{Symbol,<:Any}: A dictionary containing grid parameters.
  • allowPartial::Bool=false: If true, incomplete grid definitions are accepted without requiring all fields needed for coordinate generation.

Validation

Depending on the inferred spatial dimension, validateGrid checks the consistency of:

  • grid dimensions (m, n, o)
  • grid spacing (dx, dy, dz)
  • grid topology (:uniform, :periodic, :curvilinear)
  • boundary-condition metadata
  • user-supplied nodal coordinates for curvilinear grids

When sufficient information is available, coordinate arrays for nodes, faces, and cell centers are generated automatically.

Returns

A validated and normalized Grid object.

Throws

  • ArgumentError if required fields are missing.
  • ArgumentError if grid dimensions or spacings are invalid.
  • ArgumentError if boundary-condition metadata is inconsistent.
  • ArgumentError if supplied curvilinear coordinate arrays have incompatible dimensions.

Examples

Validate a one-dimensional grid definition:

grid = validateGrid(Dict(
    :m => 100,
    :dx => 0.01,
))

Validate an existing grid object:

grid = makeGrid(m=64, dx=1/64)

grid = validateGrid(grid)

Validate a partially specified grid:

grid = validateGrid(
    Dict(:m => 100);
    allowPartial = true,
)

Notes

Most users should construct grids using makeGrid, which calls validateGrid automatically. Direct use of validateGrid is primarily intended for internal routines, advanced workflows, or validation of externally constructed grid definitions.

source
MOLE.Grids.Grid — Type
Grid{T} <: AbstractGrid

Stores the geometric and boundary-condition metadata for a computational grid.

A Grid is the central data object used by the MOLE 2.0 grid API. It records the grid dimension, topology, cell counts, grid spacings, coordinate arrays, and boundary-condition metadata. Operators should treat Grid objects as read-only inputs.

Fields

  • dim::Int: Spatial dimension of the grid.
  • topology::Symbol: Grid topology, such as :uniform, :periodic, or :curvilinear.
  • m, n, o: Number of cells in the x-, y-, and z-directions.
  • dx, dy, dz: Grid spacing in the x-, y-, and z-directions.
  • nodes::NamedTuple: Nodal coordinate arrays.
  • faces::NamedTuple: Face coordinate arrays.
  • centers::NamedTuple: Cell-center coordinate arrays.
  • bc::BoundaryMetadata{T}: Boundary-condition metadata.

Examples

grid = makeGrid(m = 64, dx = 1/64)

grid.dim
grid.topology
grid.nodes
source
MOLE.Grids.BoundaryMetadata — Type
BoundaryMetadata{T}

Stores the boundary-condition metadata associated with a computational grid.

BoundaryMetadata is used by Grid and contains the coefficients required to define scalar boundary conditions, together with flags indicating whether each coordinate direction is periodic.

Fields

  • dc::Vector{T}: Dirichlet coefficients for each boundary.
  • nc::Vector{T}: Neumann coefficients for each boundary.
  • isPeriodic::Vector{Bool}: Periodicity flags for each coordinate direction.
  • hasData::Bool: Indicates whether boundary-condition information has been explicitly provided.

The expected lengths of dc and nc depend on the grid dimension:

DimensionLength
1D2
2D4
3D6

The length of isPeriodic is equal to the number of spatial dimensions.

Examples

bc = BoundaryMetadata(
    dc = [1.0, 1.0],
    nc = [0.0, 0.0],
    isPeriodic = [false],
    hasData = true,
)

A periodic one-dimensional grid can be represented by zero Dirichlet and Neumann coefficients:

bc = BoundaryMetadata(
    dc = [0.0, 0.0],
    nc = [0.0, 0.0],
    isPeriodic = [true],
    hasData = true,
)
source

Operators

MOLE.Operators.div — Method
div(k, m, dx; dc, nc)

Returns a one-dimensional mimetic divergence operator. Default is non periodic.

Arguments

  • k::Int: Order of accuracy
  • m::Int: Number of cells
  • dx::T: Step size
  • dc::NTuple{2,T}: Dirichlet coefficients of left and right boundaries (optional)
  • nc::NTuple{2,T}: Neumann coefficients of left and right boundaries (optional)
source
MOLE.Operators.div — Method
div(k, ticks)

Returns a m + 2 by m + 1 non-uniform mimetic divergence operator

Arguments

  • k::Int: Order of accuracy
  • ticks::AbstractArray: Edges' ticks e.g. [0 0.1 0.15 0.2 0.3 0.4 0.45]
source
MOLE.Operators.div — Method
div(k, m, dx, n, dy; dc, nc)

Returns a two-dimensional mimetic divergence operator. Default is non periodic.

Arguments

  • k::Int: Order of accuracy
  • m::Int: Number of cells in x-direction
  • dx::T: Step size in x-direction
  • n::Int: Number of cells in y-direction
  • dy::T: Step size in y-direction
  • dc::NTuple{4,T}: Dirichlet coefficients of left, right, bottom, and top boundaries (optional)
  • nc::NTuple{4,T}: Neumann coefficients of left, right, bottom, and top boundaries (optional)
source
MOLE.Operators.div — Method
div(k, xticks, yticks)

Returns a two-dimensional non-uniform mimetic divergence operator.

Arguments

  • k::Int: Order of accuracy
  • xticks::AbstractVector: Edges' ticks (x-axis)
  • yticks::AbstractVector: Edges' ticks (y-axis)
source
MOLE.Operators.grad — Method
grad(k, m, dx; dc, nc)

Returns a one-dimensional mimetic gradient operator. Default is non periodic.

Arguments

  • k::Int: Order of accuracy
  • m::Int: Number of cells
  • dx::T: Step size
  • dc::NTuple{2,T}: Dirichlet coefficients of the left and right boundaries (optional)
  • nc::NTuple{2,T}: Neumann coefficients of the left and right boundaries (optional)
source
MOLE.Operators.grad — Method
grad(k, ticks)

Returns a m + 1 by m + 2 one-dimensional non-uniform mimetic gradient operator

Arguments

  • k::Int: Order of accuracy
  • ticks::AbstractVector: Centers' ticks e.g. (0 0.5 1 3 5 7 9 9.5 10) (including the boundaries!)
source
MOLE.Operators.grad — Method
grad(k, m, dx, n, dy; dc, nc)

Returns a two-dimensional mimetic gradient operator. Default is non periodic.

Arguments

  • k::Int: Order of accuracy
  • m::Int: Number of cells in x-direction
  • dx::T: Step size in x-direction
  • n::Int: Number of cells in y-direction
  • dy::T: Step size in y-direction
  • dc::NTuple{4,T}: Dirichlet coefficients of the left, right, bottom, and top boundaries (optional)
  • nc::NTuple{4,T}: Neumann coefficients of the left, right, bottom, and top boundaries (optional)
source
MOLE.Operators.grad — Method
grad(k, xticks, yticks)

Returns a two-dimensional non-uniform mimetic gradient operator

Arguments

  • k::Int: Order of accuracy
  • xticks::AbstractVector: Centers' ticks (x-axis) (includint the boundaries!)
  • yticks::AbstractVector: Centers' ticks (y-axis) (includint the boundaries!)
source
MOLE.Operators.lap — Method
lap(k, m, dx; dc, nc)

Returns a m+2 by m+2 one-dimensional mimetic laplacian operator. Default is non periodic.

Arguments

  • k::Int: Order of accuracy
  • m::Int: Number of cells
  • dx::T: Step size
  • dc::NTuple{2,T}: Dirichlet coefficients of the left and right boundaries (optional)
  • nc::NTuple{2,T}: Neumann coefficients of the left and right boundaries (optional)
source
MOLE.Operators.lap — Method
lap(k, m, dx, n, dy; dc, nc)

Returns a two-dimensional mimetic laplacian operator. Default is non periodic.

Arguments

  • k::Int: Order of accuracy
  • m::Int: Number of cells in x-direction
  • dx::T: Step size in x-direction
  • n::Int: Number of cells in y-direction
  • dy::T: Step size in y-direction
  • dc::NTuple{4,T}: Dirichlet coefficients of the left and right boundaries (optional)
  • nc::NTuple{4,T}: Neumann coefficients of the left and right boundaries (optional)
source
MOLE.Operators.interpol — Method
interpol(m::Int, c::Real)

Construct the one-dimensional center-to-face interpolation operator.

Returns a sparse (m+1) × (m+2) matrix.

source
MOLE.Operators.interpol — Method
interpol(::Val{:centers_to_faces}, k::Int, m::Int; c=0.5)

Construct the one-dimensional center-to-face interpolation operator.

This is equivalent to interpol(m, c) for k == 2.

source
MOLE.Operators.interpol — Method
interpol(::Val{:faces_to_centers}, k::Int, m::Int; c=0.5)

Construct the one-dimensional face-to-center interpolation operator.

Returns a sparse (m+2) × (m+1) matrix.

source
MOLE.Operators.interpol — Method
interpol(::Val{:centers_to_faces}, k::Int, m::Int, n::Int; c=0.5)

Construct the two-dimensional center-to-face interpolation operator.

Maps duplicated cell-centered data [u; u] to staggered face data

[u_x_faces;
 u_y_faces]

with size ((m+1)n + m(n+1)) × 2(m+2)(n+2).

source
MOLE.Operators.interpol — Method
interpol(::Val{:faces_to_centers}, k::Int, m::Int, n::Int; c=0.5)

Construct the two-dimensional face-to-center interpolation operator.

Maps staggered face data

[g_x_faces;
 g_y_faces]

to duplicated cell-centered data

[g_x_centers;
 g_y_centers]

with size 2(m+2)(n+2) × ((m+1)n + m(n+1)).

source

Utilities

MOLE.BCs.robinBC — Method
robinBC(k, m, dx, a, b)

Returns a m+2 by m+2 one-dimensional mimetic boundary operator that imposes a boundary condition of Robin's type.

Arguments

  • k::Int: Order of accuracy
  • m::Int: Number of cells
  • dx: Step size
  • a: Dirichlet Coefficient
  • b: Neumann Coefficient
source
MOLE.BCs.ScalarBC1D — Type
Concrete scalar BC description for 1D.

Fields mirror the Octave function:
- dc: Dirichlet coefficients (left,right)
- nc: Neumann/Robin coefficients (left,right)
- v:  prescribed boundary value g (left,right)
source
MOLE.BCs.ScalarBC2D — Type
Concrete scalar BC description for 2D.

Fields mirror the Octave function:
- dc: Dirichlet coefficients (left, right, bottom, top)
- nc: Neumann/Robin coefficients (left, right, bottom, top)
- vc: prescribed boundary value g (left, right, bottom, top)
source
MOLE.BCs.addScalarBC! — Method
1D BC applicator. Mirrors Octave addScalarBC1D.
Signature keeps the discretization params (`k,m,dx`) separate from `bc`.
source
MOLE.BCs.addScalarBC! — Method
2D BC applicator. Mirrors Octave addScalarBC2D.
Signature keeps the discretization params (`k,m,dx,n,dy`) separate from `bc`.
source

Examples

The MOLE library contains examples demonstrating how to use the operators, in a broad range of partial differential equations (PDEs). More information on the mathematical content can be found in the main MOLE documentation.

Currently, the following examples are available in the MOLE Julia package.

  • Elliptic Problems
    • 1D Examples
      • elliptic1D: A script that solves the 1D Poisson's equation with Robin boundary conditions using mimetic operators.
    • 2D Examples
      • elliptic2DXDirichletYDirichlet: A script that solves the 2D Laplace equation, $\nabla^2 u = 0$, with Dirichlet boundary conditions in $x$ and $y$ using mimetic operators.
      • elliptic2DXPerYDirichlet: A script that solves the 2D Laplace equation, $\nabla^2 u = 0$, with periodic bonudary conditions in $x$ and Dirichlet boundary conditions in $y$ using mimetic operators.
  • Hyperbolic Problems
    • 1D Examples
      • burgers1D: A script that solves the 1D conservative form of inviscid Burgers equation using mimetic operators.
      • hyperbolic1D: A script that solves the 1D Hyperbolic Equation with Periodic boundary conditions using mimetic operators.
  • Parabolic Problems
    • 2D Examples
      • parabolic2D: A script that solves the 2D heat equation, $u_t = \nu \nabla^2 u$, with Dirichlet boundary conditions in $x$ and $y$ using mimetic operators.
  • Navier-Stokes Problems
    • 2D Navier-Stokes Examples
      • cylinder_flow_2D.jl: A script that solves the 2D incompressible Navier-Stokes equations in a channel with a solid cylindrical obstacle.