Hands-on tutorials for immersed boundary software, with IB2d, IBAMR (including the immersed boundary finite element method, IBFE), VisIt for visualization, and Planktos for agent-based modeling in fluid flows. By Laura A. Miller (Department of Mathematics, University of Arizona), built from tutorials taught since 2013 at UNC Chapel Hill and the University of Arizona.
The theory behind these tools is in the companion series Fluid Dynamics and IBM Theory.
Work in progress (October 2026). Every part of the plan is now written and fact-checked, and it is being reviewed again, so expect corrections. Work continues on the
master-tutorialbranch and is merged intomasteras it is reviewed. The original lectures are kept in originals/ and the original course examples in examples/legacy/.
The consolidated LaTeX version covers the software landscape and the path from an organism to a mesh, installing IBAMR with autoibamr, building examples with CMake, and current IBAMR releases. The examples and the build commands were tested with IBAMR 0.16.0 (the version on the UA cluster) and 0.19.0 (the latest release). Example IB/01 has also been built and run on Puma with the commands in chapters 1-3 (4 min 14 s on 4 cores); the other job scripts follow the same pattern. Every chapter of the plan is now written and fact-checked, and the author is reviewing them again, so expect corrections; new VisIt screenshots and new lecture videos are still to come. Part X, the archive, keeps what the course used before: the retired clusters, the hand-built installs of 2011-2019, the old course code mapped to current IBAMR, and the course logistics of 2013-2024, each slide labelled legacy.
Videos. New lecture videos will follow the new chapters. The four IB2d video tutorials by Nick Battista are public: 1 the IB method and IB2d, 2 what comes with IB2d, 3 building a geometry and its input files, 4 visualizing the output in VisIt.
| Folder | What it contains |
|---|---|
| 0-Front-Matter/ | Chapters 0.1 and 0.2: about these notes (provenance, contributors, the list of lecture videos) and the roadmap (LaTeX + PDF) |
| 1-Getting-Set-Up/ | Chapters 1, 1b, 2 and 3 (LaTeX + PDF) |
| 2-IB2d/ | Part II, chapters 4a to 4f (LaTeX + PDF) |
| 3-IBAMR-Fundamentals/ | Part III, chapters 5–16 (LaTeX + PDF), drafted |
| 4-IBFE/ | Part IV, chapters 17–25 (LaTeX + PDF), drafted |
| 5-VisIt/ | Part V, chapters 26–33 (LaTeX + PDF), drafted |
| Planktos/ | Part VI, chapters 34 (What is Planktos?) and 35 (Using Planktos) (LaTeX + PDF), drafted |
| 7-Examples-Guide/ | Part VII, chapter 36: the catalogue of examples, one page per example (LaTeX + PDF) |
| 8-Appendices/ | Appendices A (every maintained MATLAB script beside its Python version), B (glossary, references with DOIs, software versions, contributors, pictures from elsewhere, licences) and C (the exercise and homework bank, problems only) (LaTeX + PDF) |
| X-Archive/ | Part X, the archive, labelled legacy: X1 retired clusters and workflows (the lab servers, UNC's Kure, KillDevil, Dogwood and Longleaf, Arizona's Ocelote and El Gato), X2 historical install recipes (2011-2019), X3 old IBAMR and libMesh code mapped to current code, X4 course logistics (LaTeX + PDF) |
| examples/IB/ | Immersed boundary examples, each with a CMake build, a Puma job script and a README: 01 rubber band, 02 pulsatile channel, 03 tethered beam, 04 moving cylinders, 06 growing springs, 07 moving plates, 08 glycocalyx 3D, 09 curling beam, 10 jellyfish bell, 11 heart-tube pump, 12 spider ballooning, 13 carotid artery, horse and human |
| examples/IB2d/ | The tutorial's own pyIB2d examples (chapters 4c-4f): the moving band, the sawtooth pump, the pulsing heart, the stability lab (a parametrised rubber band, the sweep that made chapter 4d's tables, the shape analysis), the muscle models (length-tension, force-velocity, the crossbridge derivation checked numerically, the heart tube's activation wave, a calcium activation model), and meshes from SVG drawings (an equal-distance point sampler, and IB2d's MeshmerizeMe starfish ported to Python), with READMEs |
| examples/ConstraintIB/ | Constraint immersed boundary examples (chapter 14), each with a CMake build, a Puma job script and a README: 01 oscillating cylinder, 02 impulsively started cylinder, 03 swimming eel |
| examples/IBFE/ | Immersed boundary finite element examples: 01 tethered plate, 05 gmsh triangle, 06 active tension, 08 plate hits circle, 10 flow tank plate 3D, 12 advection–diffusion |
| examples/analysis/ | Readers for the examples' position and force files in Python and MATLAB/Octave and the drag-and-lift analysis of IB/03 (chapter 11); the VisIt scripts of Part V (frames, queries, 3D pictures, resampling and export, a Slurm job) and vtk_for_planktos.py (chapter 35) |
| examples/Planktos/ | Planktos on this series' flows (chapters 34 and 35): chapter 4f's IB2d starfish (density estimates, capture, FTLE maps, Vicsek alignment), IBFE/10's flow tank with a plate through VisIt, and the first run of chapter 35 |
| examples/support/ | The course's MATLAB exercises (the heat equation, a stiff equation, checking and plotting structure files) beside their Python versions, with the rubber band they were run on (Appendix A) |
| examples/legacy/ | The course example codes as they were, from UNC and the University of Arizona. They use the old Makefile build; the folders above replace them one by one. |
| originals/ | The original lectures (IBAMR, IBFE, VisIt, IB2d), the MATLAB exercises, and older files, kept as they were for reference (in October 2026 a few links to course file storage were taken out of three old decks) |
| pictures/ | Figures used by the LaTeX decks |
| papers/ | Open-access papers referred to in the tutorials |
ib-tutorials.sty |
The shared slide style |
Each deck compiles on its own with pdflatex, from the repository root or from its own folder, for example:
cd 1-Getting-Set-Up
pdflatex 3-Building-and-Running-IBAMR.texThe files in examples/ must keep Unix line endings: IBAMR stops with Illegal character token in input when an input file has Windows line endings. The .gitattributes file makes Git check them out that way on every system, including Windows.
Material in these tutorials was developed with many students and colleagues over the years; individual decks credit their contributors and sources.
Claude (Anthropic) was used to organize, combine, and format more than fourteen years (2012–2026) of the instructor's tutorial notes from courses and workshops at several universities.
- Slides, text and figures: Creative Commons Attribution 4.0 International (CC BY 4.0). You may share and adapt them for any purpose, as long as you give credit.
- Example code and scripts: BSD 3-Clause.
- Exceptions: files that carry their own copyright notice or credit another author keep their original terms. The example programs adapted from IBAMR keep IBAMR's BSD 3-Clause notice, figures from other sources are credited where they appear, and the papers in
papers/are under their publishers' licenses.
To credit these tutorials, cite: Miller, L. A. (2026). Using IB Software: tutorials for IB2d, IBAMR, VisIt and Planktos. https://github.com/fairyflies9/Using-IB-Software
The author also directs EquiPhysics, a nonprofit that brings horse lovers to mathematics; these tutorials are shared there too.
Please let me know if you find any issues or have suggestions for extensions. You can open an issue on this repository.