Getting Started

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.

Package Installation by OS#

Ubuntu/Debian Systems#

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

macOS Systems#

Install 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#

  1. Clone the repository:

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

  2. Build the library:

    mkdir build && cd build
cmake ..
make

  3. 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#

Many of the examples require ‘gnuplot’ to visualize the results. You can get gnuplot on macOSX with

brew install gnuplot

and on Windows downlaoding and running the file from here

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:

// transport1D.cpp - 1D advection-reaction-dispersion equation

#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]
  
  // 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)

  // Time integration loop (simplified)
  for (int i = 0; i <= iter; i++) {
    // First-order forward-time scheme
    C += dt * (D * (dis * (G * C)) - D * (V % (I * C)));
  }

  cout << C;
  return 0;
}

% elliptic1D.m - 1D Poisson's equation with Robin boundary conditions

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 for 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))

For full examples, see:

Next Steps#

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.

Contents