Feat: Add 1D Wave convergence example (Matlab & C++) ref Mathews & Fi…

[tin7]

…nk Ex 10.1

What type of PR is this? (check all applicable)

• Refactor
• Feature
• Bug Fix
• Optimization
• Example
• Documentation

Description

Academic example comparing Mimetic Finite Differences vs Standard Finite Differences for the 1D Wave Equation (Hyperbolic).

Context & Reference

• Source Problem: Example 10.1 from Numerical Methods Using MATLAB (Mathews & Fink, 2004).
• Institutional Context: Example presented in the postgraduate course "Introduction to Mimetic Difference Methods and Applications" (Prof. Jose Castillo, UNR FCEIA, Oct 2023).

Mathematical Formulation

$$\frac{\partial^2 u}{\partial t^2} = 4 \frac{\partial^2 u}{\partial x^2}, \quad x \in [0, 1], \quad t \in [0, 0.5]$$

• BC: Dirichlet $u(0,t)=0, u(1,t)=0$.
• IC: $u(x,0) = \sin(\pi x) + \sin(2\pi x)$.

Implementation Details

1. C++ (examples/cpp/wave1D_convergence.cpp):

   • Uses MOLE library
   • Time integration: Velocity Verlet.
   • Demonstrates global 2nd-order convergence (L2 norm).

2. MATLAB/Octave (examples/matlab_octave/wave1D_convergence/):

   • run_convergence_test.m: Driver script.
   • Generates comparative plots (see QA Instructions below).

Numerical Verification

Mimetic Scheme Convergence Rates (C++ Output):

Cells (m)	dx	L2 Error	Rate
20	5.0000e-02	4.3367e-04	-
40	2.5000e-02	4.9180e-05	3.14
80	1.2500e-02	5.8741e-06	3.07
160	6.2500e-03	6.4405e-07	3.19
320	3.1250e-03	5.3138e-08	3.60

Note: The observed rates > 2.0 indicate superconvergence effects typical of Mimetic operators on staggered grids with smooth initial conditions.

Related Issues & Documents

• Closes 1D Wave Equation example in mimetic and finite difference #275

QA Instructions, Screenshots, Recordings

Visual validation of the implementation:

(1) Convergence: Error vs Grid Spacing

(2) Convergence: Error vs cells

(3) Wave Profile Comparison (Coarse Grid m=20)
Visual validation of phase and amplitude accuracy on a low-resolution grid. It is noteworthy that the Mimetic method closely tracks the analytical solution even on this coarse mesh ($m=20$), exhibiting significantly less numerical dispersion than the standard Finite Difference scheme.

How to test:

1. C++: cd build && make && ./examples/cpp/wave1D_convergence
2. MATLAB: Run examples/matlab_octave/wave1D_convergence/run_convergence_test.m

Added/updated tests?

_We encourage you to test all code included with MOLE, including examples.

• Yes
• No, and this is why: please replace this line with details on why tests
  have not been included
• I need help with writing tests

Read Contributing Guide and Code of Conduct

• I have read and followed the Contributing Guide and the Code of Conduct

[optional] Are there any post deployment tasks we need to perform?

[optional] What gif best describes this PR or how it makes you feel?

[jbrzensk]

Thanks for contributing @tin7 . It will be good to have this comparison.

For the code, I am going to reference the MATLAB version, but the same suggestion may apply to the C++ code.

In the MATLAB folder, you have div, grad, lap. Please use the operators in the MOLE src/matlab_octave folder.

Also, you do not need the pictures in the PR. Those are generated by the user. You can include them in the pull request, so we can see what the results look like, but leave them out of the PR.

To check the convergence of the operator in space, you FIX the time discretization (dt) and vary the space discretization (dx). You have both varying.

Also, for the FD method, you have a staggered grid (line 34). To do a correct comparison, you need m+2 equally spaced points. The finite difference does not work on a staggered grid. Currently, this introduces additional error in the FD method. When done correctly, both of these measurements (FD and MD methods) should be really close to 2.

[tin7]

@jbrzensk

Thank you for the detailed review and the suggestions regarding the grid setup and time stepping.
Changes applied:

1. Fixed Time Step: Logic updated in both languages. dt is now calculated based on the finest mesh ($m=320$) and kept constant for all simulations to strictly isolate spatial convergence error.

2. FD Grid: The MATLAB FD solver now uses a nodal grid (linspace) with $m+2$ points to avoid staggered grid interpolation errors.

3. Removed plotting files and local operators from the PR. Plotting code is preserved but commented out in the script.

Ready for re-review.

[jbrzensk]

Getting better. I put some notes about the paths and the error. The mimetic is order 2, you should get order 2, like really close to 2, (1.99->2.01). Same for the finite difference. If you get something different, you did something wrong.

Some other notes about adding paths much simpler, and using the dot operator for scalar times matrix.

Again, thanks for this. I will probably have notes about naming the files and their folder, but thats minor. Key is to get the error to show around order 2. Once it does, change the order of the mimetic operator and ensure that it is order 4. Once yuou fix the matlab, I just assume you will fix the cpp code.

Here is what I got with a little tinkering of your code:

[jbrzensk]

Files in the current folder are automatically in the path for both Matlab and Octave.
You can add the src files to the path like other matlab examples, with

addpath('../../../src/matlab_octave');

[jbrzensk]

Use addpath instead of the four lines of code here.

[tin7]

@jbrzensk

I think that found the main reason I was still getting an apparent order higher than 2: I was measuring the error at (T = 0.5), which is a special time for this test case.

For the exact solution
u(x,t)=sin(pi x)cos(2pi t)+sin(2pi x)cos(4pi t),
the leading spatial error term (for both the 2nd-order mimetic and standard 2nd-order FD discretizations) is dominated by a phase error term proportional to sin(omega t). At (t=0.5), this vanishes for both modes:

sin(2\pi \cdot 0.5)=\sin(\pi)=0
sin(4\pi \cdot 0.5)=\sin(2\pi)=0
So the (O(h^2)) term cancels at that final time, and the next term dominates, which makes the measured rate look artificially higher (apparent superconvergence).
After changing the final time to a non-resonant value (e.g. (T=0.37)) and keeping the same setup, both methods recover the expected spatial order and the rates are very close to 2.

I will update the MATLAB test accordingly (and then mirror the same fix in the C++ version).

Thanks

[tin7]

Implemented latest review feedback and pushed commit 9ff5b39 (fixed convergence setup, updated paths, and aligned MATLAB/C++ naming)

[jbrzensk]

Thanks for the update. Looks better with the convergence.
I put some nitpick things about formatting and spacing and some extra bits not needed in the code.

Also about the naming. The wave1d_solver... should be named wave1Dsolver..., and just change the name of the "run_convergence_test.m" to wave1D_convergence.m. No need for the extra file.

[jbrzensk]

Use addpath instead of the four lines of code here.

[tin7]

As requested, I also successfully verified the 4th-order behavior locally. By changing the mimetic operator to k=4 and drastically reducing the time step to $\Delta t = 10^{-6}$ , the mimetic scheme correctly yields strict 4th-order convergence rates ($\approx 4.05$), while the standard FD baseline remains at 2.00.I will leave the pushed code set to order 2 (k=2) and Delta t = 0.001 to keep the example lightweight and aligned with the branch name, but the testing framework is now fully robust for higher-order validations.

| (m) | Mimetic Err | Rate | FD Error | Rate |
| 160 | 7.255e-08 | 4.05 | 4.020e-04 | 2.00 |
| 300 | 5.743e-09 | 4.03 | 1.150e-04 | 2.00 |