How inria-parkas/sundialsml works
Main Components
• Interface Library: This is the core of Sundials/ML. It includes modules like “sundials”, “arkode”, “cvode”, “cvodes”, “ida”, “idas”, “kinsol”, “nvectors”, and “lsolvers”. Each of these is implemented in OCaml and contains sub-components that handle the OCaml-to-C binding (for example, files like arkode_ml.c, cvode_ml.c, etc.).
• Underlying Sundials Library: Represent the external numerical solvers provided by Sundials (the C library). Although not developed in this repository, it is central to the functionality of Sundials/ML. Indicate that Sundials/ML “wraps” these low-level routines.
• Build and Configuration: Include components like the Makefile, configure files, and opam package definitions. This shows how the project is built, configured, and integrated (e.g., linking to the Sundials installation).
• Documentation & Examples: The “doc” and “examples” directories are important – they not only illustrate usage of the interface but also provide guidance and test cases. These examples span various usage scenarios (serial, OpenMP, MPI, Pthreads, etc.) and highlight different solver approaches.
• C Bindings Layer: Separate out the C layers (files with _ml.c suffix) that bridge between OCaml and the Sundials C API.
Relationships and Interactions
• From “OCaml User Code” (which may be written in client applications using Sundials/ML) to the “Interface Library” modules.
• Inside the Interface Library, show how specific modules (e.g., arkode, cvode) interact with their respective C binding components.
• From these modules, point toward the “Underlying Sundials Library” (external dependency). It’s important to illustrate that while OCaml modules drive the high-level API, they delegate performance-critical tasks to the C routines.
• Build and configuration layer interacting with both the OCaml code and the C components (e.g., via Makefile and configure scripts).
Architectural Patterns and Design Principles
• Interface Abstraction: Illustrate that the type system of OCaml is leveraged to “document” the C library usage. This abstraction helps prevent misuse by managing errors and dynamic conditions with exceptions.
• Extensibility: Use labels to indicate points where users can define nvectors, linear solvers, and nonlinear solvers in OCaml. This is a key extension point.
Technology Stack and Tools
• OCaml: As the main programming language.
• C & C Bindings: For low-level access to Sundials.
• OPAM: For package management (indicated by the opam file).
• Build Tools: Makefile, configure scripts, and related build instructions.
• Documentation Tools: The “doc” directory which includes both HTML files and PDF documentation.