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 MOLEor, 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 MOLEUsing 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.jlRunning 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.jlPreview 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.centersMOLE.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: Iftrue, 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.
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: Iftrue, 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
ArgumentErrorif required fields are missing.ArgumentErrorif grid dimensions or spacings are invalid.ArgumentErrorif boundary-condition metadata is inconsistent.ArgumentErrorif 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.
MOLE.Grids.Grid — Type
Grid{T} <: AbstractGridStores 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.nodesMOLE.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:
| Dimension | Length |
|---|---|
| 1D | 2 |
| 2D | 4 |
| 3D | 6 |
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,
)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 accuracym::Int: Number of cellsdx::T: Step sizedc::NTuple{2,T}: Dirichlet coefficients of left and right boundaries (optional)nc::NTuple{2,T}: Neumann coefficients of left and right boundaries (optional)
MOLE.Operators.div — Method
div(k, ticks)Returns a m + 2 by m + 1 non-uniform mimetic divergence operator
Arguments
k::Int: Order of accuracyticks::AbstractArray: Edges' ticks e.g. [0 0.1 0.15 0.2 0.3 0.4 0.45]
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 accuracym::Int: Number of cells in x-directiondx::T: Step size in x-directionn::Int: Number of cells in y-directiondy::T: Step size in y-directiondc::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)
MOLE.Operators.div — Method
div(k, xticks, yticks)Returns a two-dimensional non-uniform mimetic divergence operator.
Arguments
k::Int: Order of accuracyxticks::AbstractVector: Edges' ticks (x-axis)yticks::AbstractVector: Edges' ticks (y-axis)
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 accuracym::Int: Number of cellsdx::T: Step sizedc::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)
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 accuracyticks::AbstractVector: Centers' ticks e.g. (0 0.5 1 3 5 7 9 9.5 10) (including the boundaries!)
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 accuracym::Int: Number of cells in x-directiondx::T: Step size in x-directionn::Int: Number of cells in y-directiondy::T: Step size in y-directiondc::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)
MOLE.Operators.grad — Method
grad(k, xticks, yticks)Returns a two-dimensional non-uniform mimetic gradient operator
Arguments
k::Int: Order of accuracyxticks::AbstractVector: Centers' ticks (x-axis) (includint the boundaries!)yticks::AbstractVector: Centers' ticks (y-axis) (includint the boundaries!)
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 accuracym::Int: Number of cellsdx::T: Step sizedc::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)
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 accuracym::Int: Number of cells in x-directiondx::T: Step size in x-directionn::Int: Number of cells in y-directiondy::T: Step size in y-directiondc::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)
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.
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.
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.
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).
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)).
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 accuracym::Int: Number of cellsdx: Step sizea: Dirichlet Coefficientb: Neumann Coefficient
MOLE.BCs.robinBC — Method
robinBC(k, m, dx, n, dy, a, b)Alias of robinBC2D
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)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)MOLE.BCs.addScalarBC! — Method
1D BC applicator. Mirrors Octave addScalarBC1D.
Signature keeps the discretization params (`k,m,dx`) separate from `bc`.MOLE.BCs.addScalarBC! — Method
2D BC applicator. Mirrors Octave addScalarBC2D.
Signature keeps the discretization params (`k,m,dx,n,dy`) separate from `bc`.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.
- MOLE: Mimetic Operators Library Enhanced
- Examples
- Elliptic Problems
- 1D Elliptic Problems
- Elliptic 1D
- Elliptic1D Add Scalar Boundary Conditions
- 2D Elliptic Problems
- Elliptic2D X Dirichlet Y Dirichlet
- Elliptic 2D X Periodic Y Dirichlet
- Hyperbolic Problems
- 1D Hyperbolic Problems
- Hyperbolic 1D
- Burgers 1D
- Parabolic Problems
- 2D Parabolic Problems
- Parabolic2D
- Navier-Stokes Problems
- 2D Navier-Stokes Problems
- 2D Channel Flow with a Cylinder
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.
- 1D Examples
- 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.
- 1D Examples
- 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.
- 2D Examples
- 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.
- 2D Navier-Stokes Examples