Finite differences are often the first place where students see partial differential equations become algorithms. The idea is simple:

derivatives  ->  differences between neighboring grid values
PDE model    ->  algebraic equations on a mesh
solution     ->  arrays that can be measured, plotted, and tested

The purpose of this project is not to hide that process behind a black box. The purpose is to make each step visible:

The code is intentionally explicit. It is designed for lectures, guided labs, reports, and independent study.

Each example follows the same computational story:

flowchart LR
    PDE["PDE model"] --> Mesh["Spatial and temporal mesh"]
    Mesh --> Stencil["Finite-difference stencil"]
    Stencil --> Solver["Discrete solver"]
    Solver --> Exact["Exact-solution comparison"]
    Exact --> Metrics["Error metrics"]
    Exact --> Figures["Figures and animations"]
    Metrics --> Tests["Automated tests"]
    Figures --> Gallery["Results gallery"]

The repository currently includes five equation families:

All methods in this repository are finite-difference methods. The labels used in the examples describe how the discrete equations are solved or organized.

For Poisson, the examples use the traditional labels:

For Diffusion, Wave, Advection, and Advection-Diffusion, the examples use implementation labels:

This distinction is important. In transient examples, both formulations are finite-difference implementations; the time-integration scheme is stated separately, for example Explicit, Crank-Nicolson, or the centered wave update.

Classical Finite Differences/
├── CFDM/
│   ├── Poisson.py
│   ├── Diffusion.py
│   ├── Wave.py
│   ├── Advection.py
│   └── Advection_Diffusion.py
├── Common/
│   ├── Metrics.py
│   ├── Graphs.py
│   ├── ExampleTools.py
│   └── TimeIntegrators/
├── Examples/
│   ├── CFDM_Poisson_examples.py
│   ├── CFDM_Diffusion_examples.py
│   ├── CFDM_Wave_examples.py
│   ├── CFDM_Advection_examples.py
│   └── CFDM_Advection_Diffusion_examples.py
├── Results/
├── Tests/
├── assets/
├── requirements.txt
├── CITATION.cff
├── LICENSE
└── README.md

git clone https://github.com/gstinoco/Classical_Finite_Differences.git
cd Classical_Finite_Differences

A virtual environment or Conda environment is recommended.

pip install -r requirements.txt

Dependencies:

numpy
matplotlib
opencv-python
pytest

python Examples/CFDM_Poisson_examples.py

This prints error tables and writes figures under:

Results/Poisson/

Each example file can be executed directly:

Examples can also be called from Python to control cost, suppress file output, or reuse arrays in a notebook:

from Examples import CFDM_Diffusion_examples as diffusion_examples

diffusion_examples.main(
    show=False,
    save_path=None,
    nodes_1d=21,
    nodes_2d=21,
    time_steps=200,
)

Common parameters:

The Results/ directory is part of the teaching material. It provides a visual reference for the methods and a reproducible gallery of outputs.

Stationary Example
Poisson/2D_FD.png

Diffusion	Wave
Diffusion/2D_Stencil.gif	Wave/2D_Stencil.gif
Advection	Advection-Diffusion
Advection/2D_Matrix_LaxWendroff.gif	Advection_Diffusion/2D_Stencil_CN.gif

Representative outputs:

Naming convention:

Results/<Equation>/<Dimension>_<Formulation>_<Method>.<ext>

Examples:

1D_FD.png
1D_GS_Neumann_2.png
2D_Matrix_FTBS.gif
2D_Stencil_CN.gif

Poisson problems are stationary boundary-value problems that appear in electrostatics, gravitation, pressure projection, potential theory, and steady-state modeling.

Project convention:

Delta phi = -f

Available solvers:

The Neumann variants compare different finite-difference approximations for the derivative condition at the left boundary. The examples keep a Dirichlet condition at the right boundary.

Diffusion models smoothing, heat conduction, concentration spreading, and gradient-driven transport.

Typical forms:

u_t = nu u_xx
u_t = nu Delta u

Available solvers:

The 2D solver can run with an explicit update or with a Crank-Nicolson-type option:

implicit=True
lam=0.5

The wave equation models propagation with finite speed, including vibrations, signals, and oscillatory fields.

Typical forms:

u_tt = c^2 u_xx
u_tt = c^2 Delta u

Available solvers:

The implemented scheme uses centered finite differences in time and space. The first two time levels are initialized from the exact benchmark solution used by the examples.

Advection describes transport by velocity: a profile moves through the domain while the numerical method attempts to preserve its shape.

Typical forms:

u_t + a u_x = 0
u_t + a u_x + b u_y = 0

Available solvers:

Implemented schemes:

Advection-Diffusion combines transport by velocity with diffusion-driven smoothing.

Typical forms:

u_t + a u_x = nu u_xx
u_t + a u_x + b u_y = nu Delta u

Available solvers:

Example labels:

The examples impose boundary values from the exact solution whenever possible. This makes verification direct because the numerical solution can be compared point by point against a known reference.

Some schemes are included because they are pedagogically useful even when they are not the best production choice. For example, unstable or conditionally stable methods are valuable for showing why discretization decisions matter.

The examples print a common table of metrics so different methods can be compared using the same language.

Let u_ex be the exact solution and u_ap the numerical approximation.

For transient examples, the metrics are computed over the full space-time solution arrays, not only at the final time.

Run the full test suite with:

python -W error::RuntimeWarning -m pytest Tests

The warning policy is intentional. Runtime warnings such as overflow, invalid values, or division by zero often reveal unstable parameters, indexing mistakes, or boundary-condition errors.

You can also check syntax and import-time correctness with:

python -m compileall CFDM Common Examples Tests

Current tests cover:

This project can support lectures, laboratory sessions, workshops, homework discussions, and self-study.

Photo	Contributor	Affiliation	Contact
	Dr. Gerardo Tinoco Guerrero 🇲🇽 Numerical Methods, Scientific Computing & Teaching Material
	Dr. Francisco Javier Domínguez Mota 🇲🇽 Applied Mathematics & Finite Difference Methods
	Dr. José Alberto Guzmán Torres 🇲🇽 Computational Engineering & Educational Technology
	Dr. Heriberto Árias Rojas 🇲🇽 Engineering Applications & Numerical Modeling

Photo	Student	Institution	Contact
	Gabriela Pedraza-Jiménez
	Eli Chagolla-Inzunza

Photo	Student	Institution	Contact
	Jorge L. González-Figueroa
	Christopher N. Magaña-Barocio

Photo	Student	Institution	Contact
	Maria Goretti Fraga-Lopez

Institution / Support	Role in the Project
🏫 UMSNH Universidad Michoacana de San Nicolás de Hidalgo	Academic home for teaching, training, and scientific computing work related to numerical methods and applied mathematics.
🔬 SeCiHTI Secretaría de Ciencia, Humanidades, Tecnología e Innovación	Public support for science, humanities, technology, innovation, and academic development in Mexico.
🏭 SIIIA MATH: Soluciones en Ingeniería Engineering solutions and scientific computing support	Technical support for mathematical modeling, simulation, scientific computing examples, and educational software documentation.
🏛️ Aula-CIMNE Morelia Academic collaboration space	Academic collaboration environment supporting numerical methods education, computational mechanics, and knowledge transfer.

If this repository supports a course, workshop, thesis, report, publication, or derived implementation, please cite it as academic software. Citation metadata is provided in CITATION.cff, which GitHub and other tools can use to generate additional formats.

The citation below lists the main software authors. The broader research team shown above may be acknowledged when their participation is relevant to a specific course, report, or derived project.

Recommended citation:

Tinoco Guerrero, G., Domínguez Mota, F. J., Guzmán Torres, J. A., & Árias Rojas, H. (2026).
Classical Finite Differences [Software].
Universidad Michoacana de San Nicolás de Hidalgo and SIIIA MATH: Soluciones en Ingeniería.
https://github.com/gstinoco/Classical_Finite_Differences

BibTeX:

@software{tinoco_guerrero_2026_classical_finite_differences,
  author       = {Tinoco Guerrero, Gerardo and Domínguez Mota, Francisco Javier and Guzmán Torres, José Alberto and Árias Rojas, Heriberto},
  title        = {Classical Finite Differences},
  year         = {2026},
  publisher    = {Universidad Michoacana de San Nicolás de Hidalgo and SIIIA MATH: Soluciones en Ingeniería},
  type         = {Software},
  url          = {https://github.com/gstinoco/Classical_Finite_Differences},
  license      = {MIT}
}

This project is distributed under the MIT License. See LICENSE for the full license text.