MOLE: Mimetic Operators Library Enhanced

1: Description

MOLE is a high-quality (C++ & MATLAB/Octave) library that implements high-order mimetic operators to solve partial differential equations. It provides discrete analogs of the most common vector calculus operators: Gradient, Divergence, Laplacian, Bilaplacian, and Curl. These operators (highly sparse matrices) act on staggered grids (uniform, non-uniform, curvilinear) and satisfy local and global conservation laws.

Mathematics is based on the work of Corbino and Castillo, 2020. However, the user may find helpful previous publications, such as Castillo and Grone, 2003, in which similar operators were derived using a matrix analysis approach.

2: Licensing

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

3: Installation (Linux)

To use MOLE (C++ version), you need to have Armadillo C++ http://arma.sourceforge.net, SuperLU https://portal.nersc.gov/project/sparse/superlu, and OpenBLAS https://www.openblas.net installed on your computer.

Assuming a working installation of SuperLU (sudo apt install libsuperlu-dev or sudo yum install SuperLU-devel), and OpenBLAS (sudo apt install libopenblas-dev or sudo yum install openblas-devel), follow these steps:

wget https://sourceforge.net/projects/arma/files/armadillo-12.6.6.tar.xz

tar xvf armadillo-12.6.6.tar.xz

cd armadillo-12.6.6

NOTE: We suggest to use the latest stable version.

Define ARMA_USE_SUPERLU and ARMA_USE_OPENMP in include/armadillo_bits/config.hpp. Make sure that you have cmake and g++ installed before executing:

./configure

make

This will create libarmadillo.so.

Now go to mole/ and build MOLE via:

ARMA=PATH_TO_ARMADILLO_FOLDER make

Or simply:

make

if Armadillo was installed via sudo apt install libarmadillo-dev or sudo yum install armadillo-devel.

A static library named libmole.a will be created after the previous step. From this point, you need to include mole.h in your projects, specify the location of libmole.a to the linker. For the users interested in building MOLE as a shared library, specify make SHARED_LIB=1. Make sure to include mole_C++ directory in LD_LIBRARY_PATH (export LD_LIBRARY_PATH=/full/path/to/mole_C++) so the loader can find the library at runtime.

For our library's MATLAB/Octave version, the only dependency is to have MATLAB/Octave installed. The two implementations of MOLE (C++ & MATLAB/Octave) are independent; you don't need to build the C++ version if you are just interested in using MOLE from MATLAB/Octave.

4: Running Examples & Tests

Here are instructions on how to run the provided examples and tests for both the C++ and MATLAB versions of the library to help you quickly get started with MOLE.

• tests/cpp: These tests, which are automatically executed upon constructing the library's C++ version, play a crucial role in verifying the correct installation of MOLE and its dependencies. There are four tests in total.

• tests/matlab: We encourage MATLAB users to execute these tests before using MOLE by entering the tests/matlab directory and executing run_tests.m from MATLAB. These tests are analogous to those contained in tests/cpp.

• examples/cpp: These will be automatically built after calling make. We encourage C++ users to make this their entry point to familiarize themselves with this library version. The four examples are self-contained and adequately documented, and they solve typical PDEs.

• examples/matlab: Most of our examples are provided in the MATLAB scripting language. Over 30 examples range from linear one-dimensional PDEs to highly nonlinear multidimensional PDEs.

5: Documentation

The folder doc/api_docs/matlab contains generated documentation about the MATLAB/Octave API. It was generated with a tool called m2html. However, for a quick start on MOLE's MATLAB/Octave version, we recommend starting with this short guide.

For C++ users, we provide a short guide to MOLE's C++ flavor. However, for those in need of more details to interact with the library, we suggest to follow these instructions:

To generate the C++ documentation, execute:

doxygen Doxyfile (requires Doxygen and Graphviz)

this will create a folder called doc_C++ containing a set of html files. Please take a look at the index.html file to start browsing the documentation.

NOTE: 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.

6: Community Guidelines

We welcome contributions to MOLE, whether they involve adding new functionalities, providing examples, addressing existing issues, reporting bugs, or requesting new features. Please refer to our Contribution Guidelines for more details.

7: Citations

Please cite our work if you use MOLE in your research or software. Citations are helpful for the continued development and maintenance of the library

Now, some cool pictures obtained with MOLE: