Getting Started

Welcome to the getting started guide for MOLE (Mimetic Operators Library Enhanced). This guide will help you set up and run your first MOLE project.

Prerequisites

To install the MOLE library, you’ll need the following packages:

CMake (Minimum version 3.10)
OpenBLAS (Minimum version 0.3.10)
Eigen3
LAPACK (Mac only)
libomp (Mac only)

For documentation build requirements, please refer to the [Documentation Guide][doc-guide].

Package Installation by OS

Ubuntu/Debian Systems

# Install all required packages
sudo apt install cmake libopenblas-dev libeigen3-dev

macOS Systems

Install [Homebrew][homebrew] if you don’t have it already, then run:

# Install all required packages
brew install cmake openblas eigen libomp lapack

Troubleshooting Homebrew: If you encounter installation errors, try these steps:

# Fix permissions issues
sudo chown -R $(whoami) /usr/local/Cellar
# Fix shallow clone issues
git -C /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core fetch --unshallow
# Remove Java dependencies if they cause conflicts
brew uninstall --ignore-dependencies java
brew update

RHEL/CentOS/Fedora Systems

# Install all required packages
sudo yum install cmake openblas-devel eigen3-devel

Building and Installing

Clone the repository:

git clone https://github.com/csrc-sdsu/mole.git
cd mole

Build the library:
```
mkdir build && cd build
cmake ..
make
```

Install the library:

For a custom location:

cmake --install . --prefix /path/to/location

For a system location (requires privileges):

sudo cmake --install .

Or

sudo cmake --install . --prefix /path/to/privileged/location

Note: Armadillo and SuperLU will be automatically installed in the build directory during the build process.

Testing

Run from the build directory:

C++

A suite of four automatic tests that verify MOLE’s installation and dependencies. These tests run automatically during the C++ library construction.

make run_tests

MATLAB/Octave

MATLAB/Octave equivalent of the C++ test suite. We recommend running these tests before using MOLE to ensure proper setup.

make run_matlab_tests

Examples

C++

Four self-contained, well-documented examples demonstrating typical PDE solutions. These are automatically built with make and serve as an excellent starting point for C++ users.

MATLAB/Octave Examples

A collection of over 30 examples showcasing various PDE solutions, from simple linear one-dimensional problems to complex nonlinear multidimensional scenarios.

Quick Start Examples

Here are some simple examples to help you get started with MOLE:

C++ Example

transport1D example (examples/cpp/transport1D.cpp)

/**
 * This example uses MOLE to solve the 1D advection-reaction-dispersion
 * equation:
 * https://wwwbrr.cr.usgs.gov/projects/GWC_coupled/phreeqc/html/final-22.html
 */

#include "mole.h"
#include <iostream>

int main() {

  int k = 2;             // Operators' order of accuracy
  Real a = 0;            // Left boundary
  Real b = 130;          // Right boundary
  int m = 26;            // Number of cells
  Real dx = (b - a) / m; // Cell's width [m]
  Real t = 4;            // Simulation time [years]
  int iter = 208;        // Number of iterations
  Real dt = t / iter;    // Time step
  Real dis = 5;          // Dispersivity [m]
  Real vel = 15;         // Pore-water flow velocity [m/year]
  Real R = 2.5;          // Retardation (Cl^- = 1, Na^+ = 2.5)
  Real C0 = 1;           // Displacing solution concentration [mmol/kgw]

  // Get 1D mimetic operators
  Gradient G(k, m, dx);
  Divergence D(k, m, dx);
  Interpol I(m, 0.5);

  // Allocate fields
  vec C(m + 2); // Scalar field (concentrations)
  vec V(m + 1); // Vector field (velocities)

  // Impose initial conditions
  C(0) = C0;
  V.fill(vel);

  // Hydrodynamic dispersion coefficient [m^2/year]
  dis *= vel; // 75

  // dt = dt/R (retardation)
  dt /= R;

  // Time integration loop
  for (int i = 0; i <= iter; i++) {

    // First-order forward-time scheme
    C += dt * (D * (dis * (G * C)) - D * (V % (I * C)));

    // Right boundary condition (reflection)
    C(m + 1) = C(m);
  }

  // Spit out the new concentrations!
  cout << C;

  return 0;
}

MATLAB/Octave Example

elliptic 1D example (examples/matlab/elliptic1D.m)

% Solves the 1D Poisson's equation with Robin boundary conditions

clc
close all

addpath('../../src/matlab')

west = 0;  % Domain's limits
east = 1;

k = 6;  % Operator's order of accuracy
m = 2*k+1;  % Minimum number of cells to attain the desired accuracy
dx = (east-west)/m;  % Step length

L = lap(k, m, dx);  % 1D Mimetic laplacian operator

% Impose Robin BC on laplacian operator
a = 1;
b = 1;
L = L + robinBC(k, m, dx, a, b);

% 1D Staggered grid
grid = [west west+dx/2 : dx : east-dx/2 east];

% RHS
U = exp(grid)';
U(1) = 0;  % West BC
U(end) = 2*exp(1);  % East BC

U = L\U;  % Solve a linear system of equations

% Plot result
plot(grid, U, 'o')
hold on
plot(grid, exp(grid))
legend('Approximated', 'Analytical', 'Location', 'NorthWest')
title('Poisson''s equation with Robin BC')
xlabel('x')
ylabel('u(x)')

Next Steps

Check out more C++ examples in the examples/cpp/ directory
Explore the MATLAB/Octave examples in the examples/matlab/ directory
Join our community and contribute

Performing non-unary operations involving operands constructed over different grids may lead to unexpected results. While MOLE allows such operations without throwing errors, users must exercise caution when manipulating operators across different grids.

Licensing

MOLE is distributed under a GNU General Public License; please refer to the LICENSE file for more details.