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.
MOLE is distributed under a GNU General Public License; please refer to the LICENSE file for more details.
To install the MOLE library on your system, certain packages must be installed and configured beforehand. The required packages vary by operating system.
For the macOS, Homebrew needs to be installed to download the required packages. Invoke the following command in the terminal app
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Minimum Version Required: OpenBLAS 0.3.10
sudo apt install libopenblas-dev
brew install openblas
sudo yum install openblas-devel
Minimum Version Required: eigen-3
sudo apt install libeigen3-dev
brew install eigen
sudo yum install eigen3-devel
brew install libomp
brew install lapack
Clone the MOLE repository and build the library
git clone https://github.com/csrc-sdsu/mole.git
cd mole
mkdir build && cd build
cmake ..
make
To install the library in a custom location (Eg. home/mole)
cmake --install . --prefix /path/to/location
To install the library in a previledged location (Eg. /opt/mole)
sudo cmake --install .
Or
sudo cmake --install . --prefix /path/to/privileged/location
Armadillo and SuperLu will be locally installed in the build directory once the cmake .. command is passed. By following the steps outlined above, you will successfully install the necessary packages and the MOLE library on your system. The library will be installed in the location provided. The tests and examples to be executed will also be built locally inside the build directory.
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/matlabdirectory and executingrun_tests.mfrom MATLAB. These tests are analogous to those contained intests/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.
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.
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.
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:
