Adding cpp&MATLAB example - 2D imcompressible square cylinder flow by yiyuef · Pull Request #274 · csrc-sdsu/mole

yiyuef · 2026-02-07T07:10:55Z

Description

This PR adds a new C++ example cylinder_flow_2D that solves 2D incompressible channel flow past a cylinder-like obstacle (implemented as a masked no-slip region) using a projection (pressure-correction) method built on MOLE mimetic operators.

It also adds Sphinx/MyST documentation for the example and includes a representative output figure.

Type of Change

Mathematical Details

Not applicable (no new operators added).
The example solves the incompressible Navier–Stokes equations with a fractional-step (projection) method and uses MOLE discrete operators (divergence, gradient, Laplacian) for the Helmholtz/Poisson solves.

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

#211

Additional Notes

Output image cylinder_flow_2D_output1.png is included alongside the documentation page.

doc/sphinx/source/examples/Navier-Stokes/Cylinder-Flow-2D.md

examples/cpp/cylinder_flow_2D.cpp

valeriabarra · 2026-02-09T21:47:39Z

Thank you, @yiyuef for this terrific contribution!

I ran the example and can see the output figure is quite small. Can you please increase its size? Also, any specific reason why the extension .ppm was chosen for non-MAC-OS users? It is a quite uncommon and unsupported file format.

Finally, I thought we also wanted to include the MATLAB/octave version to the library. I thought you had completed that implementation, first? Thank you!

Co-authored-by: Valeria Barra <39932030+valeriabarra@users.noreply.github.com> Signed-off-by: Yiyue Feng <79966731+yiyuef@users.noreply.github.com>

yiyuef · 2026-02-12T00:58:44Z

@valeriabarra Thanks for the careful review!

You’re right about the inconsistent message and the .ppm choice. So I removed the platform-dependent PPM/PNG output and now the example only writes the three CSV outputs (U_final.csv, V_final.csv, p_final.csv). Visualization is handled via a separate gnuplot script, so the output messaging is now consistent. The reason I chose ppm is that I found cpp can output this format without outside packages.
Regarding the figure size: I updated the gnuplot script to generate a larger PNG.
markdown file also modified, to be consistant with the above change.
For the MATLAB version, I thougth I should open another PR. Because source functions in MATLAB have been changed a little bit so my old code was not good. I have looked into in and now it should work. Matlab exmaple is now also part of this PR.

examples/cpp/cylinder_flow_2D_plot.gnu

jbrzensk · 2026-02-09T23:49:10Z

examples/cpp/cylinder_flow_2D.cpp

+    if ((step % plotEvery) == 0 || step == 1 || step == nSteps) {
+      const double maxU = arma::abs(U_new).max();
+      const double maxV = arma::abs(V_new).max();
+      const double umax = maxU;


umax is made twice? maxU and umax are the same.

jbrzensk · 2026-02-09T23:50:21Z

examples/cpp/cylinder_flow_2D.cpp

+  U.submat(1, ny - 1, nx - 1, ny - 1).zeros();
+  V.submat(1, ny - 1, nx - 1, ny - 1).zeros();
+
+  U(0, 0) = 0.0;       U(0, ny - 1) = 0.0;


Split these onto their own separate lines. ( clang-format )

jbrzensk · 2026-02-09T23:51:28Z

examples/cpp/cylinder_flow_2D.cpp

+  return idx;
+}
+
+static uvec bc_bottom_indices(unsigned m, unsigned n) {


If n is void, then

c_bottom_indices(unsigned m, unsigned /*n*/)

jbrzensk · 2026-02-09T23:52:36Z

examples/cpp/cylinder_flow_2D.cpp

+#include <armadillo>
+
+// Optional Eigen (for reusable sparse factorization)
+#if defined(__has_include)


nit: # directives are not indented ( so says clang-format )

jbrzensk · 2026-02-09T23:53:34Z

examples/cpp/cylinder_flow_2D.cpp

+#endif
+
+// Mimetic operator library (in ./cpp)
+#include "mole.h"


I guess this should have armadillo down here, but maybe it doesn't work with EIGEN?

jbrzensk · 2026-02-09T23:54:31Z

examples/cpp/cylinder_flow_2D.cpp

+static uvec bc_bottom_indices(unsigned m, unsigned n) {
+  (void)n;
+  uvec idx(m + 2);
+  for (unsigned i = 0; i < m + 2; ++i) idx(i) = i;


needs braces around the idx(i) = i

jbrzensk · 2026-02-09T23:54:46Z

examples/cpp/cylinder_flow_2D.cpp

+  uvec idx(m + 2);
+  const unsigned nx = m + 2;
+  const unsigned j = n + 1;
+  for (unsigned i = 0; i < m + 2; ++i) idx(i) = i + nx * j;


braces around if

jbrzensk · 2026-02-09T23:55:18Z

examples/cpp/cylinder_flow_2D.cpp

+  uvec rowsbc;
+  if (!pieces.empty()) {
+    rowsbc = pieces[0];
+    for (size_t i = 1; i < pieces.size(); ++i) rowsbc = arma::join_cols(rowsbc, pieces[i]);


for loop needs braces {}

mdumett · 2026-03-02T20:45:44Z

This comment refers to the MATLAB implementation.

This is a very interesting and complex example. My main suggestions are mainly with respect to its documentation.

The clear command in line 5 should be removed
This example is complex. To give to the user an easy experience while reading the code, keep in mind that in the first lines of the code, one should describe what PDE is being solved, domain and geometry, initial and boundary conditions, parameter values and the algorithm. In particular de projection method.
Line 24 mentions ghost coordinates but in Mimetic Differences there are no ghost points, like in Finite Differences.
What are CN diffusion matrices?
What are cylinder mask indices?
What are U* and V*?
What are AB2 and AB1?

From the code, it is not clear why the need to apply boundary conditions (applyVelocityBCAndMask) in a finite difference manner. If the code is more documented the user can appreciate the decision of the developer.

This an important example from which many users can learn about how to deal with complicated geometries. Please, provide more documentation.

valeriabarra · 2026-03-16T21:14:57Z

Hi @yiyuef , I know you have finals this week, but will you have a chance to review this after your finals? Thank you.

yiyuef · 2026-03-16T21:17:34Z

Thank you for all the comments! I have final exams this week but I will definitely review them carefully and update my PR. Thanks again.

valeriabarra · 2026-03-25T00:12:14Z

Thank you for all the comments! I have final exams this week but I will definitely review them carefully and update my PR. Thanks again.

Hi @yiyuef , I hope your exams went well. Do you have any updates for this PR? Thank you!

yiyuef · 2026-04-01T06:39:26Z

@jbrzensk @mdumett @valeriabarra Hi all, I apologize for the late update, please check the latest version of the example code and documentation. I simplified a lot, and highlighted how I use mimetic operators in the documentation.

valeriabarra · 2026-04-01T19:41:15Z

Hi @yiyuef , I think you also need to add this example to the CMakeLists.txt file

valeriabarra · 2026-04-01T20:02:35Z

Hi @yiyuef thank you again for your contribution. In addition to my previous comments, it appears that the documentation file is failing. Have you tried to build the docs locally to test it? The two images are not rendered. Also the math typesetting is not formatted correctly. See the screenshots below of the docs preview. Thank you!

yiyuef · 2026-04-01T23:59:01Z

Hi @yiyuef , I think you also need to add this example to the CMakeLists.txt file

done.

yiyuef · 2026-04-02T00:58:37Z

@valeriabarra Prof. Barra,
I was basically checking on the preview site. And it also looks good in my vscode preview, see screenshot. How can I load the website like you did in your screenshot? Thank you!

valeriabarra · 2026-04-02T01:26:00Z

@valeriabarra Prof. Barra, I was basically checking on the preview site. And it also looks good in my vscode preview, see screenshot. How can I load the website like you did in your screenshot? Thank you!

You can see instructions on how to build the docs locally here https://github.com/csrc-sdsu/mole/tree/main/doc/sphinx

Also, please see my comment regarding the GNUplot in my code review above. Thank you!

yiyuef · 2026-04-02T04:01:14Z

@valeriabarra Prof. Barra,
I think I have fixed the issues of math formulas and output images. Now it should be all good in html preview.

valeriabarra · 2026-04-02T23:56:58Z

Hi @yiyuef , thank you very much for this terrific contribution!

@mdumett and @jbrzensk , if you are satisfied with how Yiyue has addressed your comments, please resolve them.

@yiyuef , if the others are satisfied with your changes, please reduce the number of commits in this PR. Use the interactive rebase with git rebase -i and fixup to reduce the number of commits. Thank you.

yiyuef and others added 10 commits February 6, 2026 17:58

Add 2D cylinder channel-flow example and documentation

9af6837

markdown change

91f2456

md

9469e6f

md

a2afd61

md

62528d0

md

20e7964

md

8375e89

md

38a7744

md

9bd192d

md

dc09d45

valeriabarra reviewed Feb 9, 2026

View reviewed changes

doc/sphinx/source/examples/Navier-Stokes/Cylinder-Flow-2D.md Outdated Show resolved Hide resolved

valeriabarra reviewed Feb 9, 2026

View reviewed changes

examples/cpp/cylinder_flow_2D.cpp Outdated Show resolved Hide resolved

yiyuef and others added 2 commits February 11, 2026 14:43

Update doc/sphinx/source/examples/Navier-Stokes/Cylinder-Flow-2D.md

ef6ffb4

Co-authored-by: Valeria Barra <39932030+valeriabarra@users.noreply.github.com> Signed-off-by: Yiyue Feng <79966731+yiyuef@users.noreply.github.com>

multiple changes

cb20eac

md change

b3065d1

yiyuef changed the title ~~Adding cpp example - 2D imcompressible cylinder flow~~ Adding cpp&MATLAB example - 2D imcompressible square cylinder flow Feb 12, 2026

valeriabarra reviewed Feb 12, 2026

View reviewed changes

examples/cpp/cylinder_flow_2D_plot.gnu Outdated Show resolved Hide resolved

valeriabarra requested a review from mdumett February 12, 2026 01:04

valeriabarra assigned valeriabarra and yiyuef and unassigned valeriabarra Feb 12, 2026

valeriabarra added the Examples Addition or improvement of examples that showcase the main functionality of the library label Feb 12, 2026

valeriabarra linked an issue Feb 12, 2026 that may be closed by this pull request

adding C++/matlab example, channel flow / cylinder flow #211

Open

yiyuef and others added 4 commits February 11, 2026 17:08

md change

5269b05

img update

b7d825f

cpp update - move gnu to cpp script

646af09

Merge branch 'main' into cylinder_branch

bc5be76

jbrzensk reviewed Feb 26, 2026

View reviewed changes

yiyuef and others added 13 commits March 31, 2026 22:41

code&doc big update

e8ec2c3

doc update

36bffaa

doc update

3a6cc21

doc update

60a4d50

doc update

f6a3a32

doc update

a01d6c2

doc update

5bee50e

doc update

e828723

doc update

002acca

doc update

868a768

doc update

3d8b6cc

doc update

a4a8306

Merge branch 'csrc-sdsu:main' into cylinder_branch

f0232c6

CMakeLists update

23d9901

doc html preview update

6fb1186

doc preview update, adding gunplot

3f21dbf

valeriabarra approved these changes Apr 2, 2026

View reviewed changes

Conversation

yiyuef commented Feb 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of Change

Mathematical Details

Testing

Documentation

Related Issues

Additional Notes

Uh oh!

Uh oh!

Uh oh!

valeriabarra commented Feb 9, 2026

Uh oh!

yiyuef commented Feb 12, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mdumett commented Mar 2, 2026

Uh oh!

valeriabarra commented Mar 16, 2026

Uh oh!

yiyuef commented Mar 16, 2026

Uh oh!

valeriabarra commented Mar 25, 2026

Uh oh!

yiyuef commented Apr 1, 2026

Uh oh!

valeriabarra commented Apr 1, 2026

Uh oh!

valeriabarra commented Apr 1, 2026

Uh oh!

yiyuef commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yiyuef commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

valeriabarra commented Apr 2, 2026

Uh oh!

yiyuef commented Apr 2, 2026

Uh oh!

valeriabarra commented Apr 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

yiyuef commented Feb 7, 2026 •

edited

Loading

yiyuef commented Apr 1, 2026 •

edited

Loading

yiyuef commented Apr 2, 2026 •

edited

Loading