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 (matrices) act on staggered grids (uniform and non-uniform) and satisfy local and global conservation laws.
Mathematics are based on the work of Corbino and Castillo, 2020. However, the user may find useful previous publications, such as Castillo and Grone, 2003, in which similar operators were derived using a matrix analysis approach.
MOLE is distributed under a GNU General Public License, please refer to the LICENSE file for more details.
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 get created after the previous step. From this point you just need to include mole.h
in your projects and specify the location of libmole.a
to the linker. For the users that are interested in building MOLE as a shared library, you just need to 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 the MATLAB/Octave version of our library, the only dependency is to have MATLAB/Octave installed. The two implementations of MOLE (C++ & MATLAB/Octave) are independent, that is, you don't need to build the C++ version if you are just interested in using MOLE from MATLAB/Octave.
To help you quickly get started with MOLE, here are instructions on how to run the provided examples and tests for both the C++ and MATLAB versions of the library.
-
tests_C++: These tests, automatically executed upon construction of 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 executingrun_tests.m
from MATLAB. These are analogs to the tests contained intests_C++
. -
examples_C++: 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, properly documented, and they solve typical PDEs. -
examples_MATLAB: Most of our examples are provided in the MATLAB scripting language. There are over 30 examples, ranging from linear one-dimensional PDEs to highly nonlinear multidimensional PDEs.
The folder doc_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 to start 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, just execute:
doxygen Doxyfile
(requires Doxygen and Graphviz)
this will create a folder called doc_C++
containing a set of html files. Please refer to 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 currently allows such operations without throwing errors, users must exercise caution when manipulating operators across different grids.
We warmly 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.
Please cite our work if you use MOLE in your research and/or software.
Citations are useful for the continued development and maintenance of
the library
Now, some cool pictures obtained with MOLE: