The tutorial
The tutorial teaches FOSSIL by following one body, from its STL file into a simulation grid. It is for the author of a solver, or of a grid generator, who needs geometry from a triangulated surface: distances, signs, wall points, tags, cut cells. It assumes Fortran 2003 and the basics of immersed-boundary or cut-cell methods; it does not assume any knowledge of FOSSIL. The guide explains the algorithms and the reference lists every method and argument.
The chapters
The body is dragon.stl, a real mesh with real defects: it is not watertight, and repairing it does not make it so. The tutorial keeps it that way on purpose, so that it shows where an open surface changes the answer and which queries tolerate it. Chapters 1 to 3 load, repair and place the dragon in the domain [-0.6, 0.6]³; chapters 4 to 6 compute its signed distance, point by point, in batches and as a field; chapter 7 goes to 2-D with a section of it; chapters 8 to 11 answer what an immersed-boundary or cut-cell solver asks, for a fixed and then a moving body; chapter 12 moves the batch to the GPU.
| Chapter | You learn |
|---|---|
| 1. A first surface | load_from_file, what analyze computes, accessors, is_watertight, is_manifold, save_into_file |
| 2. Repairing the surface | sanitize, fill_holes=, the stderr report, is_volume |
| 3. Placing the body | translate, rotate, resize, analyze after a transformation, clip, mirror, merge_solids |
| 4. Signed distance | distance, is_point_inside, compute_distance; the sign algorithms |
| 5. Batched queries | distance_many, SAH BVH and octree, pseudo-normal and fast winding number on an open surface |
| 6. A distance field | distance_field_object on a stretched grid: band, signs, fast sweeping |
| 7. Curves in 2-D | slice_surface, curve_object, 2-D distance and 2-D field |
| 8. Immersed-boundary queries | query_many: wall point, feature, normal, body; image_points, probe_many |
| 9. AMR tagging | box_classify_many (cut, near, inside, outside), tag_block |
| 10. Cut cells | curve%cut_cells and cut_cells_3d: fractions, apertures, fluid pieces, flagged cells |
| 11. Moving bodies | poses, pose= queries, move, state_changes, swept_cells_2d |
| 12. On the GPU | enter_device, distance_many_device, exit_device; the nvfortran build |
The chapters pass files to each other, so run them in order:
How the examples are made
Every snippet in these pages is part of a real program in docs/examples/src, one per chapter (tutNN_<name>.f90), and every output shown is what that program printed: captured, not typed. Comment markers in the sources (!region NAME ... !endregion NAME) cut the programs into the parts the pages show. The programs print with explicit formats only, so their output does not depend on the compiler.
bash scripts/docs_examples.sh rebuilds the library (fobis build --mode static-gnu), builds every program, runs them in order in one scratch directory holding dragon.stl, cube-01.stl and naca0012-ascii.stl, and regenerates the snippets and outputs these pages include. To build one chapter by hand, with the library built in static/:
gfortran -I static/mod docs/examples/src/tut01_first_surface.f90 static/libfossil.a -o tut01
cp src/tests/dragon.stl . && ./tut01