mesh_sieve/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2//! # mesh-sieve
3//!
4//! mesh-sieve is a modular, high-performance Rust library for mesh and data management, designed for scientific computing and PDE codes. It provides abstractions for mesh topology, field data, parallel partitioning, and communication, supporting both serial and MPI-based distributed workflows.
5//!
6//! ## Features
7//! - Mesh topology and Sieve data structures for flexible mesh connectivity
8//! - Atlas and Section types for mapping mesh points to data arrays
9//! - Pluggable communication backends (serial, Rayon, MPI) for ghost exchange and mesh distribution
10//! - Built-in support for graph partitioning (Metis, custom algorithms)
11//! - MPI integration for distributed mesh and data exchange
12//! - Extensive serial, parallel, and property-based testing
13//!
14//! ## Determinism
15//!
16//! All randomized decisions use `SmallRng` seeds drawn from configuration so runs are
17//! reproducible. Unit tests fix seeds explicitly to ensure deterministic behavior.
18//!
19//! ## Usage
20//! Add `mesh-sieve` as a dependency in your `Cargo.toml` and enable features as needed:
21//!
22//! ```toml
23//! [dependencies]
24//! mesh-sieve = "1.2.1"
25//! # Optional features:
26//! # features = ["mpi-support","rayon","metis-support"]
27//! ```
28//!
29//! For a complete API reference and usage guide, see [API_Guide.md](API_Guide.md).
30//!
31//! ## Migration highlights
32//! See [docs/MIGRATING.md](docs/MIGRATING.md) for more details on recent API
33//! changes:
34//! - Fallible map access via `try_restrict_*` helpers and the [`FallibleMap`]
35//!   trait.
36//! - [`Bundle::assemble`] now averages element-wise; use
37//!   [`Bundle::assemble_with`] with a [`SliceReducer`](crate::data::bundle::SliceReducer)
38//!   for custom behavior.
39//! - `data::refine::delta::SliceDelta` replaces the deprecated `Delta` alias.
40//!
41//! ## Shared payloads
42//! When payloads are large or shared across many arrows, instantiate a sieve with `Payload = Arc<T>`.
43//! Traversal and algorithms will clone the `Arc` handle (cheap) without copying `T`.
44//! Use type aliases [`topology::sieve::InMemorySieveArc`],
45//! [`topology::sieve::InMemoryOrientedSieveArc`], and [`topology::sieve::InMemoryStackArc`] for convenience.
46//! Avoid wrappers that convert between `T` and `Arc<T>` on the fly; they add allocations and defeat sharing.
47
48//! Public prelude for mesh-sieve: mesh/data-management library for PDE codes
49//!
50//! All Sieve implementations provide `points()`, `base_points()`, and `cap_points()` iterators for global point set access.
51
52// Re-export our major subsystems:
53pub mod adapt;
54pub mod algs;
55pub mod data;
56pub mod debug_invariants;
57pub mod discretization;
58pub mod forest;
59pub mod geometry;
60pub mod io;
61pub mod mesh_error;
62pub mod mesh_generation;
63pub mod mesh_graph;
64pub mod overlap;
65#[cfg(feature = "mpi-support")]
66pub mod partitioning;
67pub mod physics;
68pub mod section;
69pub mod topology;
70
71pub use debug_invariants::DebugInvariants;
72
73/// A convenient prelude to import the most-used traits & types:
74pub mod prelude {
75    pub use crate::algs::assembly::{
76        AssemblyCommTags, assemble_section_with_ownership, assemble_section_with_tags_and_ownership,
77    };
78    pub use crate::algs::communicator::Communicator;
79    #[cfg(feature = "mpi-support")]
80    pub use crate::algs::communicator::MpiComm;
81    #[cfg(feature = "rayon")]
82    pub use crate::algs::communicator::RayonComm;
83    pub use crate::algs::completion::{
84        complete_section, complete_section_with_ownership,
85        complete_section_with_tags_and_ownership, complete_sieve, complete_stack,
86        complete_stack_with_tags,
87    };
88    #[cfg(feature = "metis-support")]
89    pub use crate::algs::distribute::MetisPartitioner;
90    pub use crate::algs::distribute::{
91        CustomPartitioner, DistributionConfig, ProvidedPartition, distribute_with_overlap,
92        distribute_with_overlap_periodic,
93    };
94    pub use crate::algs::point_sf::PointSF;
95    pub use crate::algs::rcm::distributed_rcm;
96    pub use crate::algs::renumber::{
97        StratifiedOrdering, renumber_coordinate_dm, renumber_points, renumber_points_stratified,
98        stratified_permutation,
99    };
100    pub use crate::data::atlas::Atlas;
101    pub use crate::data::bc::{
102        FieldDofIndices, LabelQuery, apply_dirichlet_to_constrained_section,
103        apply_dirichlet_to_constrained_section_fields, apply_dirichlet_to_section,
104        apply_dirichlet_to_section_fields,
105    };
106    pub use crate::data::constrained_section::{
107        ConstrainedSection, ConstraintSet, DofConstraint, apply_constraints_to_section,
108    };
109    pub use crate::data::coordinate_dm::{CoordinateDM, CoordinateNumbering};
110    pub use crate::data::coordinates::{Coordinates, MeshVelocity};
111    pub use crate::data::discretization::{
112        Discretization, DiscretizationMetadata, FieldDiscretization, RegionKey,
113    };
114    pub use crate::data::global_map::LocalToGlobalMap;
115    pub use crate::data::hanging_node_constraints::{
116        HangingDofConstraint, HangingNodeConstraints, LinearConstraintTerm,
117        apply_hanging_constraints_to_section,
118    };
119    pub use crate::data::multi_section::{FieldSection, MultiSection};
120    #[cfg(feature = "map-adapter")]
121    pub use crate::data::section::Map;
122    pub use crate::data::section::Section;
123    pub use crate::debug_invariants::DebugInvariants;
124    pub use crate::discretization::runtime::{
125        Basis, DofMap, ElementRuntime, ElementTabulation, QuadratureRule, assemble_local_matrix,
126        assemble_local_vector, cell_vertices, local_load_vector, local_stiffness_matrix,
127        runtime_from_metadata, tabulate_element,
128    };
129    pub use crate::io::MeshBundle;
130    pub use crate::overlap::delta::{AddDelta, CopyDelta, ValueDelta};
131    pub use crate::overlap::overlap::Overlap;
132    pub use crate::physics::fe::{
133        ElementMatrices, ReferenceElementEvaluation, assemble_element_matrices,
134        evaluate_reference_element, integrate_reference_scalar,
135    };
136    pub use crate::topology::bounds::{PayloadLike, PointLike};
137    pub use crate::topology::cell_type::CellType;
138    pub use crate::topology::labels::LabelSet;
139    pub use crate::topology::ownership::{OwnershipEntry, PointOwnership};
140    pub use crate::topology::periodic::{
141        PeriodicMap, PointEquivalence, collapse_points, quotient_sieve,
142    };
143    pub use crate::topology::point::PointId;
144    pub use crate::topology::sieve::{
145        InMemoryOrientedSieve, InMemoryOrientedSieveArc, InMemorySieve, InMemorySieveArc,
146        InMemorySieveDeterministic, InMemoryStackArc, MutableSieve, Orientation, OrientedSieve,
147        Sieve, SieveBuildExt, SieveQueryExt,
148    };
149    pub use crate::topology::stack::{InMemoryStack, Stack};
150}
mesh_sieve/lib.rs

mesh_sieve/
lib.rs
