Learning Module Structure

This document proposes a learning path for the Rust training material in this repository. The structure follows the existing examples in source-code/, but groups them into teaching modules rather than treating the directory order as the curriculum itself.

The intended audience is learners who know how to program, but are new to Rust or new to using Rust for scientific and technical computing.

Module 1: Getting Started With Rust Projects

Primary examples:

Topics:

  • Rust project layout.
  • Cargo.toml, Cargo.lock, and src/main.rs.
  • cargo check, cargo build, and cargo run.
  • Adding dependencies with cargo add.
  • Basic command-line parsing with clap.
  • Reading compiler diagnostics.

Goal:

Participants should be able to open, build, run, and lightly modify a small Rust binary project.

Related module text:

  • learning-modules/getting-started-with-rust-projects.md

Module 2: Scalar Computation And Numeric Basics

Primary examples:

Topics:

  • Integer and floating-point types.
  • Type inference and explicit type annotations.
  • Numeric literals.
  • Arithmetic operators.
  • Integer division and remainder.
  • Floating-point functions and constants.
  • Complex numbers through num-complex.
  • Physical quantities through uom.
  • Differences from C and C++ numeric promotion rules.

Goal:

Participants should understand how Rust represents scalar values and how to write small numerical expressions without relying on implicit conversions.

Related module text:

  • learning-modules/scalar-computation-and-numeric-basics.md

Module 3: Control Flow And Program Structure

Primary examples:

Topics:

  • if and else.
  • while loops.
  • for loops over ranges and collections.
  • Function definitions.
  • Return values.
  • Enums.
  • match.
  • Introductory source modules.

Goal:

Participants should be able to write small programs with explicit control flow and factor repeated work into functions.

Related module text:

  • learning-modules/control-flow-and-program-structure.md

Module 4: Ownership, Borrowing, And Mutation

Primary examples:

Topics:

  • Immutable bindings by default.
  • Mutable bindings.
  • Move semantics.
  • Copy types.
  • Shared references.
  • Mutable references.
  • Borrowing slices instead of whole owned containers.

Goal:

Participants should develop a working mental model for ownership and borrowing before moving on to larger data structures.

Related module text:

  • learning-modules/ownership-borrowing-and-mutation.md

Optional contrast:

This material can be used to show the kinds of memory-safety and concurrency issues Rust's ownership model is designed to prevent or make explicit.

Module 5: Data Modeling With Structs And Methods

Primary examples:

Topics:

  • Defining structs.
  • Implementing methods with impl.
  • Associated functions.
  • Encapsulation through methods.
  • Generic structs.
  • Trait bounds on implementations.

Goal:

Participants should be able to define small domain types and attach behavior to those types using methods.

Related module text:

  • learning-modules/data-modeling-with-structs-and-methods.md

Module 6: Reusable Abstractions With Traits

Primary examples:

Topics:

  • Standard trait implementations.
  • Display, Index, IndexMut, and TryFrom.
  • User-defined traits.
  • Trait bounds.
  • Crate-provided numeric traits.
  • Trait objects.
  • dyn Trait.
  • Static and dynamic dispatch at a conceptual level.

Goal:

Participants should understand how Rust expresses shared behavior without classical inheritance.

Related module text:

  • learning-modules/reusable-abstractions-with-traits.md

Module 7: Collections, Iterators, And Text Data

Primary examples:

Topics:

  • Vectors.
  • Iterator adapters.
  • map, filter, fold, and scan.
  • Hash maps and hash sets.
  • Reading and writing text files.
  • Buffered I/O.
  • Owned String values and borrowed &str views.
  • Line-based parsing of timestamped records.
  • Date/time parsing with chrono.
  • Structural matching while parsing text fields.

Goal:

Participants should be able to process collections and simple text data using idiomatic iterator-based Rust.

Related module text:

  • learning-modules/collections-iterators-and-text-data.md

Module 8: Error Handling

Primary example:

Topics:

  • Option.
  • Result.
  • The ? operator.
  • Propagating errors from functions.
  • Converting from simple examples to fallible command-line programs.

Goal:

Participants should be able to recognize and write Rust code that handles missing values and recoverable errors explicitly.

Related module text:

  • learning-modules/error-handling.md

Module 9: Project Organization, Libraries, And Tests

Primary examples:

Topics:

  • Shared library code in src/lib.rs.
  • Multiple executables in one Cargo package.
  • [[bin]] entries in Cargo.toml.
  • Reusing library code from several binaries.
  • Unit tests.
  • #[cfg(test)] test modules.
  • Numerical checks with tolerances.

Goal:

Participants should understand how a Cargo package can grow beyond a single main.rs, and how to keep shared code and tests organized as examples become larger.

Related module text:

  • learning-modules/project-organization-libraries-and-tests.md

Module 10: Randomness And Reproducible Runs

Primary example:

Topics:

  • Random number generators.
  • Distributions.
  • Seeding.
  • Reproducibility.
  • Producing data for visualization.

Goal:

Participants should understand how to generate random data in a controlled way and why explicit seeds matter for scientific examples.

Related module text:

  • learning-modules/randomness-and-reproducible-runs.md

Module 11: Data Parallelism With Rayon

Primary example:

Topics:

  • Data parallelism.
  • Rayon parallel iterators.
  • into_par_iter.
  • Parallel map and collect.
  • Avoiding shared mutable state.
  • Controlling worker threads with RAYON_NUM_THREADS.
  • Benchmarking serial and parallel implementations.

Goal:

Participants should understand how to use Rayon for independent per-element work, and how to reason about when data parallelism is likely to help.

Related module text:

  • learning-modules/data-parallelism-with-rayon.md

Module 12: Integrated Numerical Example: Julia Set

Primary example group:

Topics:

  • Complex arithmetic.
  • Arrays and matrices.
  • Command-line configuration.
  • TOML configuration files.
  • Image-like numerical output.
  • Multiple implementations of the same algorithm.
  • Comparing implementation styles.

Goal:

Participants should see how the earlier language features combine in a compact scientific-computing example.

Related module text:

  • learning-modules/integrated-numerical-example-julia-set.md

Suggested placement:

This module works well after the core language modules, alongside the other integrated numerical examples.

Module 13: Integrated Numerical Example: N-Body Simulation

Primary example:

Topics:

  • Structs and methods in a larger example.
  • Random initialization.
  • Command-line parameters.
  • CSV output.
  • Time integration.
  • Energy diagnostics.
  • Python visualization helpers.
  • Separating simulation state, output, and analysis.

Goal:

Participants should see a small but realistic scientific program that combines many of the earlier concepts in one place.

Related module text:

  • learning-modules/integrated-numerical-example-n-body-simulation.md

Suggested placement:

This module should be treated as an integrated numerical example, similar in role to the Julia set module, rather than as part of the initial feature-by-feature sequence.

Module 14: Multidimensional Arrays And Stencil Computation

Primary example group:

Topics:

  • Owned two-dimensional arrays with ndarray::Array2.
  • Shapes, indexing, slices, and borrowed array views.
  • Mutable views and conditional initialization.
  • Aligned traversal with ndarray::Zip.
  • Five-point stencil computation.
  • Double buffering and allocation reuse.
  • Read-only APIs with ArrayView2.
  • Broadcasting one-dimensional coordinate arrays into a Gaussian field.
  • TOML configuration with nested structs and a tagged enum.
  • Separating reproducible scientific parameters from operational CLI flags.
  • Singular value decomposition with an OpenBLAS-backed crate.
  • Matrix reconstruction with dot and a diagonal matrix.
  • Maximum absolute and Frobenius error measures.
  • Scientific unit tests and cross-implementation black-box tests.
  • Behavior-preserving refactoring.

Goal:

Participants should be able to express a small multidimensional numerical algorithm with ndarray, configure reproducible runs, and reason about ownership, views, broadcasting, mutation, and the tests that protect a refactoring. They should also be able to use an external linear-algebra routine, reconstruct a matrix from a compact SVD, and assess the numerical difference from the original.

Related module text:

  • learning-modules/multidimensional-arrays-and-stencil-computation.md

Suggested placement:

This module belongs near the end of the course. It revisits ownership, project-level testing, and numerical validation through a practical multidimensional-array workflow.

Optional extended example:

  • source-code/hdf5-snapshot persists an ndarray field and metadata in a chunked, compressed HDF5 dataset, then demonstrates a full round trip and a hyperslab read. It also bridges this module to the native-library deployment concerns in Module 15.

Module 15: Native Library Interoperability

Primary examples:

Topics:

  • Complete binding stack for a home-grown C++ library with no -sys crate.
  • Stable C facade around a C++ class with an opaque handle and status codes.
  • Handwritten raw Rust declarations and native compilation from build.rs.
  • Raw C bindings through a -sys crate.
  • Checked conversion between Rust and C integer types.
  • Raw pointers, NonNull, and native aligned allocation.
  • Safe slice-based APIs around a small unsafe implementation.
  • Comparison with an existing high-level crate built on the same -sys layer.
  • Survey of scientific -sys crates and their wrapper crates.
  • Safe aligned buffers and owning FFTW plan types from the fftw crate.
  • RAII cleanup of native allocations and opaque handles with Drop.
  • Resource drop order and stable native heap addresses.
  • FFTW planner serialization and concurrent plan execution.
  • Real-to-complex spectrum shape and inverse normalization.
  • One-sided mean-square power normalization.
  • Optional CSV output paths parsed with clap.
  • Separate Matplotlib visualization of the signal and power spectrum.
  • Boundary-condition tests and numerical round-trip validation.
  • Linking against a system-provided HPC library.

Goal:

Participants should be able to build a small complete binding when an in-house C++ library has no existing Rust crate, then recognize which layers a -sys crate and a high-level wrapper supply. They should be able to encode native API obligations in an owning Rust wrapper, keep unsafe local, and test both the boundary contract and the scientific result while retaining responsibility for normalization, output semantics, and scientific validation.

Related module text:

  • learning-modules/native-library-interoperability.md

Suggested placement:

This is the final core module. It relies on ownership, errors, library organization, tests, arrays, and numerical tolerances, then demonstrates how Rust can be introduced around an established HPC library.

Optional Module: Rust By Contrast With C++

Primary example:

Topics:

  • Memory safety.
  • Dangling references.
  • Data races.
  • Numeric conversions.
  • The difference between preventing errors and documenting discipline.

Goal:

Participants with a C or C++ background should get a concrete sense of which problems Rust is designed to move from run time to compile time.

This module can be used near the beginning for motivation or later as a reflective comparison after ownership and borrowing have been introduced.

Suggested Teaching Order

A compact course can use this order:

  1. Getting Started With Rust Projects.
  2. Scalar Computation And Numeric Basics.
  3. Control Flow And Program Structure.
  4. Ownership, Borrowing, And Mutation.
  5. Data Modeling With Structs And Methods.
  6. Reusable Abstractions With Traits.
  7. Collections, Iterators, And Text Data.
  8. Error Handling.
  9. Project Organization, Libraries, And Tests.
  10. Randomness And Reproducible Runs.
  11. Data Parallelism With Rayon.
  12. Integrated Numerical Example: Julia Set.
  13. Integrated Numerical Example: N-Body Simulation.
  14. Multidimensional Arrays And Stencil Computation.
  15. Native Library Interoperability.

For a shorter course, the Julia set example can be used as the main integrated example, while the N-body simulation, heat-diffusion refactoring, and native interoperability module can be left as additional integrated examples.

For a course aimed at scientific programmers, the numerical, randomness, Julia-set, N-body, multidimensional-array, and native-interoperability modules should receive more time than the purely syntactic examples.