mGFD: Meshless Generalized Finite Differences 📐☁️

A high-performance Python ecosystem for Point Cloud Generation and PDE solving on highly irregular domains using Generalized Finite Differences.

📑 Table of Contents

• 🌟 Overview
• 📦 Installation
• 🛠️ Quick Start
• 🔬 Research & Datasets
• 📜 Citation & Credits

🌟 Overview

mGFD is a complete meshless computational suite. Traditional methods (like Finite Elements or Finite Volumes) require complex and restrictive mesh generation. mGFD completely bypasses this limitation by solving Partial Differential Equations (PDEs) directly on unstructured point clouds.

This makes it exceptionally powerful for modeling physics in complex, real-world geometries such as natural lakes, islands, or custom engineering domains.

🚀 Key Features

• ☁️ Integrated Cloud Generator: A powerful engine to automatically generate 2D point clouds from geographic contour boundaries (supports Poisson-Disk sampling, Lloyd relaxation, and grid-based methods).
• 📐 Pure Meshless Solvers: Discretize and solve PDEs using only local neighbor stencils. No mesh required!
• ⚡ Stationary Solvers: Out-of-the-box support for Poisson-type equations and generalized stationary problems.
• 🔥 Transient Solvers: First-order (Heat, Advection-Diffusion) and Second-order (Wave) time integrations.
• 🧩 Modular Architecture: Highly professional PEP-8 compliant sub-package architecture. Logically separated domains (mGFD.solvers, mGFD.core) and specialized pipelines (e.g. mGFD.cloud_generator.core.point_generation).

📦 Installation

mGFD relies on a robust scientific stack (numpy, scipy, shapely, opencv-python-headless).

The easiest way to install the package is directly from PyPI:

pip install mGFD

To install the package from source (useful for development):

git clone https://github.com/gstinoco/mGFD.git
cd mGFD
pip install -e .

This will automatically install both the Python API and the mgfd-cloud command-line interface.

🛠️ Quick Start

The true power of mGFD lies in its ability to go from raw geographic contours to a solved PDE in just two steps.

Step 1: Generate a Point Cloud

The mgfd-cloud CLI tool automates the process of converting geometric boundaries into valid computational domains.

[!TIP] Visual Contour Generator If you don't have a geographic dataset, you can visually draw and export your own contour boundaries using our mGFD CloudGenerator Web Tool.

# General help
mgfd-cloud --help

# Generate a point cloud with natural (Poisson-Disk) distribution and interior islands (holes)
mgfd-cloud generate --input contours.csv --output my_cloud.csv --method natural --density 0.5 --inside-regions

# Generate a point cloud with regular (Grid-based) distribution
mgfd-cloud generate --input contours.csv --output my_cloud_grid.csv --method regular

# Reduce the density of an existing cloud silently (multiplier=2 means ~75% reduction)
mgfd-cloud -q reduce --input high_density.csv --output low_density.csv --multiplier 2

Step 2: Solve a PDE

Use the Python API to load your cloud and run a meshless solver.

import numpy as np
from mGFD.io.io import load_points
from mGFD import Stationary

# 1. Load the generated point cloud
p = load_points("my_cloud.csv")

# 2. Define the analytical boundary condition
phi = lambda x, y: np.exp(x + y)

# 3. Define the right-hand side forcing function
f_stat = lambda x, y: 2 * np.exp(x + y)

# 4. Define the differential operator [D, E, A, B, C, F]
L_stat = np.vstack([[0], [0], [2], [0], [2], [0]])

# 5. Solve the equation! (Verbose mode on by default in scripts, but off in the core library)
u_ap, vec = Stationary(p, phi, f_stat, operator=L_stat, verbose=True)

import numpy as np
from mGFD.io.io import load_points
from mGFD import TimeDerivative1

p = load_points("my_cloud.csv")
v, t1 = 0.01, 100

f_heat = lambda x, y, t, coef: np.exp(-2 * np.pi**2 * coef[0] * t) * np.cos(np.pi * x) * np.cos(np.pi * y)
L_heat = np.vstack([[0], [0], [2*v], [0], [2*v], [0]])

u_ap, vec = TimeDerivative1(p, f_heat, t1, [v], operator=L_heat, implicit=True, lam=0.5, verbose=True)

import numpy as np
from mGFD.io.io import load_points
from mGFD import TimeDerivative2

p = load_points("my_cloud.csv")
c, t2 = 0.5, 50

f_wave = lambda x, y, t, coef: np.cos(np.sqrt(2) * np.pi * coef[0] * t) * np.sin(np.pi * x) * np.sin(np.pi * y)
g_wave = lambda x, y, t, coef: 0.0 * x  # Initial velocity
L_wave = np.vstack([[0], [0], [2*c**2], [0], [2*c**2], [0]])

u_ap, vec = TimeDerivative2(p, f_wave, g_wave, t2, [c], operator=L_wave, implicit=True, lam=0.5, verbose=True)

🔬 Research & Datasets

Looking for the mathematical formulation, real-world geographic lake datasets (Lake Patzcuaro, Caspian Sea, etc.), or reproducible benchmarking scripts?

👉 Explore the Research Laboratory (/research/README.md)

The research/ directory contains our complete academic suite, including experimental data, geographic boundary files, VTK results, and the exact theoretical explanations associated with our scientific publications.

📜 Citation & Credits

This project is open-sourced under the MIT License.

If you use this library or the core mathematical methodology in your research, please cite our reference paper:

@article{tinoco2025mgfd,
  title={mGFD: A meshless generalized finite difference method},
  author={Tinoco-Guerrero, Gerardo and Domínguez-Mota, Francisco Javier and Guzmán-Torres, José Alberto and Pedraza-Jiménez, Gabriela and Tinoco-Ruiz, José Gerardo},
  journal={Computers & Mathematics with Applications},
  volume={195},
  pages={396--418},
  year={2025},
  publisher={Elsevier},
  doi={10.1016/j.camwa.2025.07.034}
}