oxifft_adapter_mpi/lib.rs
1//! # OxiFFT MPI Adapter
2//!
3//! `oxifft-adapter-mpi` is a **Pure-Rust-v2 ยง5 quarantine crate**. It isolates the
4//! C MPI FFI (the `mpi` โ `mpi-sys` / `libffi-sys` / `clang-sys` dependency chain)
5//! out of the core `oxifft` facade so that `oxifft`'s `--all-features` dependency
6//! closure stays 100% Pure Rust. All distributed-FFT functionality that needs to
7//! link against a system MPI library lives here instead of in `oxifft`.
8//!
9//! This crate provides distributed FFT computation using MPI, similar to FFTW-MPI.
10//! It enables computing large-scale FFTs across multiple processes.
11//!
12//! # Features
13//!
14//! - 2D, 3D, and N-D distributed FFTs
15//! - Slab decomposition (row-major distribution)
16//! - Pencil decomposition (2D process grid) for 3D transforms
17//! - Efficient all-to-all transpose operations
18//! - Compatible with FFTW-MPI data layouts
19//!
20//! # Example
21//!
22//! ```ignore
23//! use oxifft_adapter_mpi::{MpiPool, MpiPlan2D, MpiFlags};
24//! use mpi::topology::Communicator;
25//!
26//! // Initialize MPI
27//! let universe = mpi::initialize().unwrap();
28//! let world = universe.world();
29//!
30//! // Create MPI pool
31//! let pool = MpiPool::new(world.duplicate());
32//!
33//! // Get local allocation size
34//! let (local_n0, local_0_start, alloc_local) = local_size_2d(n0, n1, &pool);
35//!
36//! // Create plan
37//! let plan = MpiPlan2D::new(n0, n1, Direction::Forward, MpiFlags::default(), &pool)?;
38//!
39//! // Execute
40//! let mut data = vec![Complex::zero(); alloc_local];
41//! plan.execute_inplace(&mut data);
42//! ```
43
44// Allow pedantic/nursery warnings that are intentional in FFT code:
45#![allow(clippy::similar_names)] // fwd/bwd, real/imag pairs are intentionally similar
46#![allow(clippy::many_single_char_names)] // FFT math uses i, j, k, n, m by convention
47#![allow(clippy::cast_precision_loss)] // FFT size computations use float for math
48#![allow(clippy::cast_sign_loss)] // stride/offset calculations need signed/unsigned
49#![allow(clippy::cast_possible_wrap)] // stride calculations need careful wrapping
50#![allow(clippy::missing_panics_doc)] // many internal functions assert preconditions
51#![allow(clippy::must_use_candidate)] // internal helpers don't need must_use
52#![allow(clippy::doc_markdown)] // allow flexibility in documentation formatting
53#![allow(clippy::incompatible_msrv)] // allow using newer features when available
54#![allow(clippy::needless_range_loop)] // explicit loops are clearer for FFT indices
55#![allow(clippy::wildcard_imports)] // use super::* in submodules is fine
56#![allow(clippy::too_many_arguments)] // FFT plans legitimately need many params
57#![allow(clippy::assign_op_pattern)] // a = a op b in codelet math avoids confusion
58#![allow(clippy::ptr_as_ptr)] // casting raw pointers in FFT is pervasive
59#![allow(clippy::suboptimal_flops)] // manual FMA control may be intentional
60#![allow(clippy::imprecise_flops)] // sqrt of squares may be intentional
61#![allow(clippy::not_unsafe_ptr_arg_deref)] // FFT internal ops are safe
62#![allow(clippy::unnecessary_wraps)] // wrapping for API consistency
63#![allow(clippy::too_many_lines)] // FFT functions can be long
64#![allow(clippy::suspicious_arithmetic_impl)] // complex arithmetic is intentional
65#![allow(clippy::only_used_in_recursion)] // recursive FFT is intentional
66#![allow(clippy::float_cmp)] // intentional float comparison in tests
67#![allow(clippy::cast_possible_truncation)] // deliberate truncation
68#![allow(clippy::ptr_cast_constness)] // pointer const casting common in FFT
69#![allow(clippy::significant_drop_tightening)] // locking patterns are intentional
70#![allow(clippy::type_complexity)] // complex return types are needed for FFT APIs
71#![allow(clippy::duplicate_mod)] // conditional compilation requires this
72#![allow(clippy::suspicious_operation_groupings)] // FFT math has specific operator groupings
73#![allow(clippy::missing_const_for_fn)] // many fns could be const but don't need to be
74#![allow(clippy::return_self_not_must_use)] // builder patterns don't need must_use everywhere
75#![allow(clippy::use_self)] // explicit type names preferred for clarity in FFT code
76#![allow(clippy::option_if_let_else)] // if-let-else is clearer than map_or in some cases
77#![allow(clippy::redundant_else)] // explicit else improves readability
78#![allow(clippy::if_not_else)] // negated conditions are sometimes clearer
79#![allow(clippy::unnested_or_patterns)] // flat patterns are easier to read
80#![allow(clippy::unreadable_literal)] // FFT constants appear as hex/long literals
81#![allow(clippy::unused_self)] // some trait methods require &self but don't use it
82#![allow(clippy::redundant_closure_for_method_calls)] // explicit closures can be clearer
83#![allow(clippy::unnecessary_cast)] // casts explicit for type documentation
84#![allow(clippy::inline_always)] // FFT codelets need inline(always) for performance
85#![allow(clippy::approx_constant)] // FFT constants may approximate std consts intentionally
86#![allow(clippy::manual_let_else)] // let-else not always clearer in FFT context
87#![allow(clippy::iter_without_into_iter)] // not all iterators need IntoIterator
88#![allow(clippy::implicit_clone)] // cloning via deref is idiomatic
89#![allow(clippy::cast_lossless)] // explicit casting preferred for documentation
90#![allow(clippy::trivially_copy_pass_by_ref)] // API consistency for small types
91#![allow(clippy::map_unwrap_or)] // map().unwrap_or() is clearer sometimes
92#![allow(clippy::explicit_iter_loop)] // explicit .iter() is clear
93#![allow(clippy::derive_partial_eq_without_eq)] // not all PartialEq types need Eq
94#![allow(clippy::single_match_else)] // single match + else is sometimes clearer
95#![allow(clippy::match_same_arms)] // identical arms for documentation/future changes
96#![allow(clippy::items_after_statements)] // local items near usage is fine
97#![allow(clippy::manual_assert)] // manual if + panic is sometimes clearer
98#![allow(clippy::std_instead_of_core)] // std re-exports are fine
99#![allow(clippy::separated_literal_suffix)] // literal suffixes may be detached
100#![allow(clippy::used_underscore_binding)] // underscore bindings used intentionally
101#![allow(clippy::manual_div_ceil)] // manual div_ceil for clarity
102#![allow(clippy::if_then_some_else_none)] // explicit if/else preferred sometimes
103#![allow(clippy::struct_field_names)] // field names may match struct name
104#![allow(clippy::default_trait_access)] // Default::default() is fine
105#![allow(clippy::expl_impl_clone_on_copy)] // explicit Clone for Copy types is intentional
106#![allow(clippy::format_push_string)] // format! appended to String is fine
107#![allow(clippy::needless_pass_by_value)] // pass by value for API ergonomics
108#![allow(clippy::copy_iterator)] // iterators may impl Copy
109#![allow(clippy::manual_clamp)] // manual clamp for clarity
110#![allow(clippy::manual_is_variant_and)] // explicit matching is fine
111#![allow(clippy::unseparated_literal_suffix)] // literal suffixes style choice
112#![allow(clippy::checked_conversions)] // explicit conversion checks preferred
113#![allow(clippy::semicolon_if_nothing_returned)] // statement style
114#![allow(clippy::ref_as_ptr)] // ref as pointer for low-level FFT
115#![allow(clippy::ptr_eq)]
116// raw pointer comparison
117
118mod distribution;
119mod error;
120mod local_size;
121mod plans;
122mod pool;
123mod transpose;
124
125pub use distribution::{Distribution, LocalPartition};
126pub use error::MpiError;
127pub use local_size::{
128 local_size_2d, local_size_2d_r2c, local_size_2d_transposed, local_size_3d, local_size_3d_r2c,
129 local_size_nd,
130};
131pub use plans::{
132 MpiPlan2D, MpiPlan3D, MpiPlanND, MpiRealPlan2D, MpiRealPlan3D, PencilGrid, PencilPlan3D,
133};
134pub use pool::{MpiFloat, MpiPool};
135pub use transpose::{
136 distributed_transpose, distributed_transpose_batched, distributed_transpose_inplace,
137};
138
139use oxifft::api::Flags;
140
141/// MPI-specific planning flags.
142#[derive(Debug, Clone, Copy, Default)]
143pub struct MpiFlags {
144 /// Base FFT planning flags.
145 pub base: Flags,
146 /// Output data in transposed layout (avoids final transpose).
147 /// Corresponds to FFTW_MPI_TRANSPOSED_OUT.
148 pub transposed_out: bool,
149 /// Input data is already in the transposed distribution (corresponds to
150 /// `FFTW_MPI_TRANSPOSED_IN`).
151 ///
152 /// The transposed distribution is exactly the one [`Self::transposed_out`]
153 /// produces: distributed over the *second* global axis rather than the first
154 /// (`[local_n1][n0]` for [`MpiPlan2D`], `[local_n1][n0][n2]` for
155 /// [`MpiPlan3D`], `[local_stride][n0]` for [`MpiPlanND`] where
156 /// `stride = product(dims[1..])`). The values it carries are *untransformed*
157 /// input; the flag describes layout only.
158 ///
159 /// Setting it mirrors the pipeline โ the (now local) first axis is
160 /// transformed before the single transpose that restores the slab, instead of
161 /// after โ so the standard FFTW-MPI idiom of a `transposed_out` forward
162 /// followed by a `transposed_in` inverse performs one `alltoallv` per
163 /// transform instead of two.
164 ///
165 /// For the **real** plans the flag describes the half-complex array, so it is
166 /// meaningful on c2r ([`MpiRealPlan2D::c2r`] / [`MpiRealPlan3D::c2r`], whose
167 /// *input* is half-complex) and is rejected with [`MpiError::FftError`] on
168 /// r2c, whose input is the never-transposed real-space slab. This matches
169 /// FFTW-MPI, which pairs `FFTW_MPI_TRANSPOSED_OUT` on r2c with
170 /// `FFTW_MPI_TRANSPOSED_IN` on c2r.
171 ///
172 /// Both transposed flags are a **slab-decomposition** concept and apply only
173 /// to the plans that take an `MpiFlags`. [`PencilPlan3D`] takes a plain
174 /// `oxifft::api::Flags` instead: its 2-D process grid defines no single
175 /// "second axis" to redistribute over, so neither transposed layout exists
176 /// there and neither flag can be passed to it.
177 pub transposed_in: bool,
178}
179
180impl MpiFlags {
181 /// Create new MPI flags with default settings.
182 pub fn new() -> Self {
183 Self::default()
184 }
185
186 /// Set the base FFT planning flags.
187 pub fn with_base(mut self, flags: Flags) -> Self {
188 self.base = flags;
189 self
190 }
191
192 /// Enable transposed output (skips final transpose).
193 pub fn transposed_out(mut self) -> Self {
194 self.transposed_out = true;
195 self
196 }
197
198 /// Indicate that input is already transposed.
199 pub fn transposed_in(mut self) -> Self {
200 self.transposed_in = true;
201 self
202 }
203
204 /// Convenience: create ESTIMATE flags.
205 pub fn estimate() -> Self {
206 Self {
207 base: Flags::ESTIMATE,
208 ..Default::default()
209 }
210 }
211
212 /// Convenience: create MEASURE flags.
213 pub fn measure() -> Self {
214 Self {
215 base: Flags::MEASURE,
216 ..Default::default()
217 }
218 }
219}