Convergence Validator

A script that verifies finite‑difference solver convergence rates. Included in a professor’s course materials.

---

📖 Overview

Convergence Validator is a Python script designed to test the convergence behavior of finite‑difference approximations. By computing numerical derivatives and comparing them to an analytical true derivative, it quantifies how the error changes as the step size h decreases. The script then plots the observed convergence order against the expected theoretical order.

✨ Features

• Finite‑difference schemes: Supports forward and central difference methods.
• Automatic convergence study: Computes errors for a range of step sizes and returns a structured pandas.DataFrame.
• Convergence order estimation: Uses log‑log linear regression to compute the observed order.
• Quality visualisation: Generates a log‑log plot of error vs. step size, overlaid with the expected theoretical line.
• Easy to extend: Modular functions let you plug in any scalar function and analytical derivative.

📦 Installation

Clone the repository and install the required packages:

git clone https://github.com/Archsec-Emman/convergence-validator.git
cd convergence-validator
pip install -r requirements.txt

Requirements:

• numpy
• pandas
• matplotlib

🚀 Quick Start

The script comes with a ready‑to‑run example that uses the central difference method to approximate the derivative of sin(x) at x = 1.0:

python validate_convergence.py

This will:

1. Compute the derivative approximation for step sizes from 10⁻¹ down to 10⁻⁸.
2. Calculate the absolute error against the true derivative (cos(1.0)).
3. Print the observed convergence order (expected order for central difference is 2.0).
4. Save a log‑log plot as convergence_plot.png and display it.

🧪 Usage

1. Define your function and its true derivative

import numpy as np

f = np.sin                     # function to differentiate
true_deriv = np.cos(1.0)       # true derivative at the test point

2. Create a convergence study

from validate_convergence import convergence_study

h_values = 10.0 ** np.linspace(-1, -8, 20)   # step sizes from 0.1 to 1e-8
df = convergence_study(f, x_test=1.0, true_derivative=true_deriv,
                       h_values=h_values, method='central')

3. Plot and analyse

from validate_convergence import plot_convergence

observed_order = plot_convergence(df, expected_order=2.0)

The function prints the observed order and returns it for further use.

📚 Functions Reference

solve_finite_difference(f, x0, h, method='forward')

Compute the finite‑difference approximation of the derivative of f at x0 using step size h.

• method: either 'forward' or 'central'.
• Returns the approximate derivative.

convergence_study(func, x_test, true_derivative, h_values, method='forward')

Perform a convergence study over a list of step sizes.

• Returns a pandas.DataFrame with columns 'h', 'approx', 'error', 'log_h', 'log_error'.

plot_convergence(df, expected_order=1.0)

Plot the error vs. step size on a log‑log scale and overlay the expected theoretical line.

• Fits a straight line to the log‑log data to estimate the observed convergence order.
• Saves the plot as convergence_plot.png and displays it.
• Returns the observed order.

📈 Example Output

When you run the built‑in example, you will see something like:

Observed convergence order: 1.999 (expected 2.0)

And a plot that clearly shows the error decreasing at the expected rate.

📦 Dependencies

• Python 3.6+
• NumPy
• pandas
• matplotlib

All dependencies are listed in requirements.txt.

📄 License

This project is licensed under the MIT License – see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! If you have ideas for new features (e.g., higher‑order schemes, Richardson extrapolation), feel free to open an issue or submit a pull request.

📬 Contact & Support

• GitHub Issues: https://github.com/Archsec-Emman/convergence-validator/issues
• Author: Archsec-Emman

---

If you find this script useful in your coursework or research, please consider starring the repository. ⭐