Contributing to MOLE: Comprehensive Guide

Contributing to MOLE: Comprehensive Guide#

Thank you for considering contributing to MOLE (Mimetic Operators Library Enhanced)! This guide provides detailed instructions for contributing to the MOLE project, whether you’re adding core functionality, examples, or documentation.

Getting Started#

Prerequisites#

Before contributing, ensure you have:

For MATLAB/Octave: MATLAB R2016b+ or GNU Octave 4.0+
For C++: CMake 3.10+, OpenBLAS, Eigen3, Armadillo
For Documentation: Python 3.7+, Sphinx, Doxygen

Setting Up Development Environment#

Fork the Repository: Fork the MOLE repository to your GitHub account

Clone Your Fork:

git clone https://github.com/YOUR_USERNAME/mole.git
cd mole

Create a Development Branch:

git checkout -b feature/your-feature-name

Create an Issue or start from an existing one:

Tackle an existing issue. We keep a list of good first issues that are self-contained and suitable for a newcomer to try and work on.
If there is no existing Issue describing what you want to report/discuss/propose to the community, please create a new Issue
Once you are ready with your contribution (whether it is for core functionality, examples, or documentation), follow the guidelines below and remember to link your open Pull Request (PR) with the Issue describing what you propose to contribute. It is very important for the community project management to keep organized PR-Issue pairs. If you are not sure how to link a PR with an Issue, please review these Linking a Pull Request to an Issue guidelines from GitHub.

Contributing to Core Functionality#

Core functionality includes mimetic operators, boundary conditions, and utility functions that form the foundation of the MOLE library.

Core API Structure#

The MOLE library follows a consistent structure across MATLAB and C++ implementations:

MATLAB/Octave Core Functions#

Core functions are located in src/matlab_octave/ and follow this pattern:

function OUTPUT = functionName(k, m, dx, ...)
% BRIEF_DESCRIPTION
%
% Parameters:
%                k : Order of accuracy
%                m : Number of cells (along x-axis for multidimensional)
%               dx : Step size (along x-axis for multidimensional)
%    (additional parameters as needed)
%
% Returns:
%          OUTPUT : Sparse matrix representing the operator
%
% ----------------------------------------------------------------------------
% SPDX-License-Identifier: GPL-3.0-or-later
% © 2008-2024 San Diego State University Research Foundation (SDSURF).
% See LICENSE file or https://www.gnu.org/licenses/gpl-3.0.html for details.
% ----------------------------------------------------------------------------

    % Input validation
    assert(k >= 2, 'Order of accuracy k must be >= 2');
    assert(mod(k, 2) == 0, 'Order of accuracy k must be even');
    assert(m >= 2*k+1, ['Number of cells m must be >= ' num2str(2*k+1) ' for k = ' num2str(k)]);
    
    % Implementation
    % ...
    
end

C++ Core Classes#

C++ implementations are in src/cpp/ and follow this pattern:

/*
 * SPDX-License-Identifier: GPL-3.0-or-later
 * © 2008-2024 San Diego State University Research Foundation (SDSURF).
 * See LICENSE file or https://www.gnu.org/licenses/gpl-3.0.html for details.
 */

/**
 * @file classname.h
 * @brief Brief description
 * @date Creation date
 */

#ifndef CLASSNAME_H
#define CLASSNAME_H

#include "required_headers.h"

/**
 * @brief Brief class description
 */
class ClassName : public sp_mat {
public:
    using sp_mat::operator=;
    
    /**
     * @brief Constructor description
     * @param k Order of accuracy
     * @param m Number of cells
     * @param dx Step size
     */
    ClassName(u16 k, u32 m, Real dx);
    
    // Additional constructors for 2D, 3D, etc.
};

#endif // CLASSNAME_H

Core Function Categories#

When contributing core functionality, identify which category your contribution fits:

Differential Operators: grad, div, lap, curl
Interpolation Functions: interpol, interpol2D, interpol3D
Boundary Conditions: robinBC, mixedBC, addScalarBC
Utility Functions: jacobian2D, jacobian3D, weights
Grid Functions: Curvilinear and non-uniform grid support

Core Function Requirements#

Consistent Interface: Follow the parameter ordering convention: (k, m, dx, n, dy, o, dz, ...)
Input Validation: Validate all input parameters with clear error messages
Sparse Matrix Output: Return sparse matrices for efficiency
Boundary Condition Support: Consider how your operator interacts with boundary conditions
Multidimensional Support: Provide 1D, 2D, and 3D versions where applicable
Documentation: Include comprehensive function documentation

Example: Adding a New Operator#

If adding a new operator, follow this checklist:

MATLAB Implementation (src/matlab_octave/newoperator.m):

function OP = newoperator(k, m, dx)
% Returns a new mimetic operator
%
% Parameters:
%                k : Order of accuracy
%                m : Number of cells
%               dx : Step size

    % Validation
    assert(k >= 2 && mod(k, 2) == 0, 'k must be even and >= 2');
    
    % Implementation using existing operators
    G = grad(k, m, dx);
    D = div(k, m, dx);
    
    % Combine operators as needed
    OP = someOperation(G, D);
end

C++ Implementation (src/cpp/newoperator.h and src/cpp/newoperator.cpp)
Add to API Documentation (doc/sphinx/source/api/)
Create Test Examples (see Examples section)

Contributing Examples#

Examples demonstrate how to use MOLE to solve specific PDEs and are crucial for user education.

Example Structure and Organization#

Examples are organized by PDE type in the examples/ directory:

examples/
├── matlab_octave/         # MATLAB/Octave examples
│   ├── elliptic1D.m       # Basic examples
│   ├── parabolic2D.m      # 2D examples
│   └── compact_operators/ # Specialized examples
└── cpp/                   # C++ examples
    ├── elliptic1D.cpp
    └── transport1D.cpp

Example Categories#

Organize your examples by PDE type:

Elliptic: Steady-state problems (Poisson, Laplace)
Parabolic: Time-dependent diffusion (heat equation, reaction-diffusion)
Hyperbolic: Wave-like phenomena (advection, wave equation)
Mixed: Problems involving multiple PDE types
Specialized: Navier-Stokes, Schrödinger, etc.

MATLAB/Octave Example Template#

% Solves the [EQUATION NAME] with [BOUNDARY CONDITIONS]
% [Brief description of the physics and mathematical formulation]

clc
close all

addpath('../../src/matlab_octave')  % REQUIRED: Add path to MOLE library

%% Problem Parameters
% [Describe each parameter with physical meaning]
k = 2;              % Order of accuracy
m = 50;             % Number of cells
west = 0;           % Domain limits
east = 1;
dx = (east-west)/m; % Grid spacing

%% Physical Parameters
% [Define problem-specific parameters]
alpha = 1;          % Thermal diffusivity (example)
t_final = 1;        % Simulation time

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

%% Operator Construction
L = lap(k, m, dx);                    % Laplacian operator
L = L + robinBC(k, m, dx, a, b);      % Add boundary conditions

%% Initial and Boundary Conditions
U = initial_condition(xgrid);         % Define initial condition
U(1) = boundary_value_west;           % West boundary
U(end) = boundary_value_east;         % East boundary

%% Time Integration (if applicable)
dt = dx^2/(4*alpha);                  % CFL condition
L_time = alpha*dt*L + speye(size(L)); % Time-stepping operator

for t = 0:dt:t_final
    % Plotting
    plot(xgrid, U, 'LineWidth', 2)
    title(sprintf('Time = %.3f', t))
    xlabel('x')
    ylabel('u(x,t)')
    drawnow
    
    % Time step
    U = L_time * U;
end

%% Analytical Solution Comparison (if available)
U_analytical = analytical_solution(xgrid, t_final);
plot(xgrid, U, 'o-', xgrid, U_analytical, '--')
legend('Numerical', 'Analytical')

C++ Example Template#

/**
 * @file example_name.cpp
 * @brief Solves the [EQUATION NAME] with [BOUNDARY CONDITIONS]
 * 
 * [Detailed description of the physics and mathematical formulation]
 * 
 * Equation: [Mathematical equation in LaTeX-style comments]
 * Domain: [Domain description]
 * Boundary Conditions: [BC description]
 */

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

using namespace arma;

int main() {
    // Problem parameters
    constexpr u16 k = 2;        // Order of accuracy
    constexpr u32 m = 50;       // Number of cells
    constexpr Real dx = 1.0/m;  // Grid spacing
    
    // Physical parameters
    constexpr Real alpha = 1.0; // Thermal diffusivity
    constexpr Real t_final = 1.0;
    
    // Construct operators
    Laplacian L(k, m, dx);
    RobinBC BC(k, m, dx, a, b);
    L = L + BC;
    
    // Initial conditions
    vec U = initial_condition();
    
    // Time integration
    Real dt = dx*dx/(4*alpha);
    sp_mat L_time = alpha*dt*L + speye(size(L));
    
    for (Real t = 0; t <= t_final; t += dt) {
        // Output current solution
        std::cout << "Time: " << std::fixed << std::setprecision(3) << t << std::endl;
        
        // Time step
        U = L_time * U;
    }
    
    // Output final solution
    std::cout << "Final solution:" << std::endl;
    U.print();
    
    return 0;
}

Example Requirements#

Self-contained: Each example should run independently
Well-commented: Explain the physics, mathematics, and implementation
Parameter Documentation: Describe all parameters and their physical meaning
Clear Output: Include appropriate visualization or numerical output
Validation: Compare with analytical solutions when possible
Consistent Naming: Use descriptive variable names following MOLE conventions

Mathematical Documentation Requirements#

Each example should include:

Mathematical Formulation: Clear statement of the PDE being solved
Domain Description: Spatial and temporal domains
Boundary Conditions: Precise specification of BCs
Initial Conditions: For time-dependent problems
Analytical Solution: If available, for validation

Contributing to Documentation#

Documentation contributions help users understand and effectively use MOLE.

Documentation Structure#

MOLE uses Sphinx for user documentation and Doxygen for API reference:

doc/
├── sphinx/                 # User documentation
│   └── source/
│       ├── examples/       # Example documentation
│       ├── api/           # API references
│       └── math_functions/ # Mathematical background
└── doxygen/               # API documentation

Example Documentation Template#

Create documentation for examples in doc/sphinx/source/examples/[Category]/[Dimension]/:

### ExampleName

Brief description of what this example solves.

$$
\text{Mathematical equation in LaTeX}
$$

with domain $x \in [a,b]$ and boundary conditions:

$$
\text{Boundary condition equations}
$$

#### Mathematical Background

[Detailed explanation of the physics and mathematics]

#### Implementation Details

[Key implementation considerations, numerical methods used]

#### Results

[Description of expected results, plots, validation]

---

This example is implemented in:
- [MATLAB/Octave](https://github.com/csrc-sdsu/mole/blob/main/examples/matlab_octave/example_name.m)
- [C++](https://github.com/csrc-sdsu/mole/blob/main/examples/cpp/example_name.cpp) *(if available)*

#### Variants

Additional variants with different boundary conditions or parameters:
- [Variant 1](link_to_variant)
- [Variant 2](link_to_variant)

Documentation Guidelines#

Mathematical Notation: Use LaTeX for equations
Code References: Link to actual implementation files
Cross-references: Link related examples and API functions
Images: Include plots and diagrams where helpful
Consistent Structure: Follow the established template

Code Standards and Guidelines#

MATLAB/Octave Standards#

Function Names: Use descriptive names following the existing convention
Variable Names: Use clear, descriptive variable names
Comments: Document complex algorithms and physics
Error Handling: Use assert for input validation
Performance: Use sparse matrices, avoid loops when possible

C++ Standards#

Naming Convention:
- Classes: PascalCase
- Functions: camelCase
- Variables: snake_case for local, camelCase for members
Headers: Include proper copyright and license headers
Documentation: Use Doxygen-style comments
Memory Management: Use smart pointers when appropriate
Performance: Leverage Armadillo’s optimizations

General Guidelines#

Consistency: Follow existing code patterns
Testing: Ensure your contributions work with provided examples
Documentation: Document all public interfaces
License: Include appropriate license headers
Dependencies: Minimize external dependencies

Testing and Validation#

Testing Your Contributions#

Unit Testing: Test individual functions with known inputs/outputs
Integration Testing: Test how your contribution works with existing code
Convergence Testing: Verify order of accuracy for new operators
Example Testing: Ensure examples run and produce expected results

Validation Methods#

Analytical Solutions: Compare with known exact solutions
Convergence Studies: Verify theoretical order of accuracy
Conservation Laws: Check that operators preserve conservation properties
Cross-platform Testing: Test on both MATLAB and Octave (for MATLAB code)

Performance Considerations#

Sparse Matrix Efficiency: Ensure operators are sparse
Memory Usage: Monitor memory consumption for large problems
Computational Complexity: Document algorithmic complexity
Scalability: Test with various problem sizes

Submission Process#

Before Submitting#

Code Review: Review your code for style and functionality
Testing: Run all relevant tests and examples
Documentation: Ensure documentation is complete and accurate
Commit Messages: Write clear, descriptive commit messages
Atomic commits: Please make your commits well-organized and atomic, using git rebase --interactive as needed

Pull Request Guidelines#

Title: Use descriptive title indicating what was added/changed
Description: Provide detailed description of changes
Testing: Describe testing performed
Examples: Include or reference relevant examples
Documentation: Link to any new documentation
PR/Issue pair: Link your PR to an existing Issue that describes your intended contribution

Pull Request Template#

## Description
Brief description of changes made.

## Type of Change
- [ ] New core functionality
- [ ] New example
- [ ] Documentation update
- [ ] Bug fix
- [ ] Performance improvement

## Mathematical Details
[For new operators] Mathematical formulation and properties.

## Testing
- [ ] Unit tests pass
- [ ] Examples run successfully
- [ ] Convergence studies completed (if applicable)
- [ ] Cross-platform compatibility verified

## Documentation
- [ ] Code is well-commented
- [ ] API documentation updated
- [ ] Example documentation added (if applicable)
- [ ] Mathematical background provided

## Related Issues
Fixes #(issue number)

## Additional Notes
Any additional information or context.

Review Process#

Automated Checks: CI/CD will run automated tests
Code Review: Maintainers will review code quality and consistency
Mathematical Review: Mathematical correctness will be verified
Documentation Review: Documentation completeness will be checked
Performance Review: Performance impact will be assessed

Getting Help#

Resources#

Documentation: Read the online documentation
Examples: Study existing examples for patterns and best practices
Issues: Check GitHub issues for known problems
Discussions: Use GitHub Discussions for questions and ideas

Contact#

For questions, support, or contributions, contact the MOLE maintainers at:

For specific types of support:

GitHub Issues: For bug reports and feature requests
GitHub Discussions: For general questions and discussions

Contributing License Agreement#

By contributing to MOLE, you agree that your contributions will be licensed under the GNU General Public License v3.0 or later. Ensure you have the right to license your contributions under this license.

Authorship and Recognition#

MOLE contains components authored by many individuals from the computational science community. We believe it is essential that contributors receive appropriate recognition through both informal acknowledgment and academically-recognized credit systems such as publications and citations.

Authorship Criteria#

Status as a named author in MOLE publications, the user manual, and DOI-bearing archives will be granted to those who:

Make significant contributions to MOLE in any of the following areas:
- Implementation of core functionality (operators, boundary conditions, utilities)
- Creation of comprehensive examples and tutorials
- Documentation and mathematical framework development
- Conceptualization of new features or mathematical approaches
- Code review, testing, and validation
- Community building and user support
Maintain and support their contributions over time, including:
- Responding to issues related to their contributions
- Updating code to maintain compatibility
- Providing ongoing documentation and support

Recognition Process#

Automatic Recognition: Maintainers will monitor contributions and add qualifying contributors to the AUTHORS file
Self-Nomination: If you believe your contributions meet the authorship criteria but haven’t been acknowledged, please:
- Email the maintainers (see Contact section)
- Create a GitHub issue describing your contributions
Periodic Review: The maintainer team regularly reviews the contributor list to ensure proper recognition

Publication Guidelines#

MOLE Software Publications#

Authors of publications about MOLE as a whole, including:

Software papers and technical reports
DOI-bearing software archives
Major release announcements
Comprehensive method descriptions

shall offer co-authorship to all individuals listed in the AUTHORS file at the time of submission.

Publications Using MOLE Features#

Authors of publications that describe specific MOLE contributions or new features shall:

Review the AUTHORS file to identify relevant contributors
Evaluate the intellectual contributions of listed authors to the specific work
Offer co-authorship to those who made significant intellectual contributions to the featured work
At minimum, acknowledge MOLE and cite appropriate references

Publications Using MOLE for Research#

No co-authorship expectation exists for those publishing research that uses MOLE as a computational tool (versus creating new features in MOLE). However:

Citation: Please cite MOLE appropriately (see CITATION.cff)
Acknowledgment: Consider acknowledging significant support or advice received from MOLE developers
Judgment: Use your best judgment regarding the significance of support received in developing your use case and interpreting results

Citing MOLE#

When using MOLE in your research, please cite:

@misc{mole,
  title = {{MOLE}: Mimetic Operators Library Enhanced},
  author = {[See AUTHORS file for complete list]},
  url = {https://github.com/csrc-sdsu/mole},
  note = {Version X.X.X},
  year = {2024}
}