kryst 4.0.4

Krylov subspace and preconditioned iterative solvers for dense and sparse linear systems, with shared and distributed memory parallelism.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168

use crate::error::KError;
use std::fmt;
use std::str::FromStr;

/// Unified coarse-level strategy for distributed preconditioners.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum DistCoarseStrategy {
    /// No coarse correction (rank-local only).
    None,
    /// Gather to rank 0 and solve on the root.
    RootGather,
    /// Per-rank local prototype (optionally with halo correction).
    LocalPrototype,
    /// External distributed backend (e.g., SuperLU_DIST) when available.
    SuperLuDist,
}

/// Explicit coarse ownership policy for distributed coarse-grid operators/solves.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum DistCoarsePolicy {
    /// Gather coarse system/solve state to root rank only.
    RootGather,
    /// Replicate coarse system state on all ranks.
    Replicated,
    /// Route through an external distributed backend.
    External,
}

impl Default for DistCoarsePolicy {
    fn default() -> Self {
        Self::RootGather
    }
}

impl FromStr for DistCoarsePolicy {
    type Err = KError;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        match value.to_lowercase().as_str() {
            "root" | "root_gather" | "gather" => Ok(Self::RootGather),
            "replicated" | "replicate" | "all" => Ok(Self::Replicated),
            "external" | "backend" | "superlu_dist" => Ok(Self::External),
            other => Err(KError::InvalidInput(format!(
                "invalid dist coarse policy: {other}"
            ))),
        }
    }
}

/// Policy for repartitioning the coarse grid in distributed AMG setups.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum DistCoarseRepartition {
    /// Preserve the fine-grid ownership partition.
    Keep,
    /// Build an even contiguous row partition over all ranks.
    Uniform,
    /// Route setup through a root-owned coarse partition.
    Root,
}

impl Default for DistCoarseRepartition {
    fn default() -> Self {
        Self::Keep
    }
}

impl FromStr for DistCoarseRepartition {
    type Err = KError;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        match value.to_lowercase().as_str() {
            "keep" | "fine" | "inherit" => Ok(Self::Keep),
            "uniform" | "block" | "contiguous" => Ok(Self::Uniform),
            "hybrid" | "local" => Ok(Self::Uniform),
            "root" | "root_owned" => Ok(Self::Root),
            other => Err(KError::InvalidInput(format!(
                "invalid dist coarse repartition policy: {other}"
            ))),
        }
    }
}

/// Explicit route for the coarse solve backend in distributed AMG.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum DistCoarseSolverRoute {
    /// Choose the backend implied by other settings.
    Auto,
    /// Force gathered root-level solve path.
    Root,
    /// Force local prototype coarse path (fallback/prototyping).
    Local,
    /// Force SuperLU_DIST coarse routing when available.
    SuperLuDist,
}

impl Default for DistCoarseSolverRoute {
    fn default() -> Self {
        Self::Auto
    }
}

impl FromStr for DistCoarseSolverRoute {
    type Err = KError;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        match value.to_lowercase().as_str() {
            "auto" => Ok(Self::Auto),
            "root" | "root_gather" | "gather" => Ok(Self::Root),
            "local" | "local_prototype" | "hybrid" => Ok(Self::Local),
            "superlu_dist" | "superludist" => Ok(Self::SuperLuDist),
            other => Err(KError::InvalidInput(format!(
                "invalid dist coarse solver route: {other}"
            ))),
        }
    }
}

impl DistCoarseStrategy {
    pub fn is_rank_local(self) -> bool {
        matches!(
            self,
            DistCoarseStrategy::None | DistCoarseStrategy::LocalPrototype
        )
    }

    pub fn is_collective(self) -> bool {
        matches!(
            self,
            DistCoarseStrategy::RootGather | DistCoarseStrategy::SuperLuDist
        )
    }
}

impl Default for DistCoarseStrategy {
    fn default() -> Self {
        DistCoarseStrategy::RootGather
    }
}

impl fmt::Display for DistCoarseStrategy {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let label = match self {
            DistCoarseStrategy::None => "none",
            DistCoarseStrategy::RootGather => "root_gather",
            DistCoarseStrategy::LocalPrototype => "local_prototype",
            DistCoarseStrategy::SuperLuDist => "superlu_dist",
        };
        write!(f, "{label}")
    }
}

impl FromStr for DistCoarseStrategy {
    type Err = KError;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        match value.to_lowercase().as_str() {
            "none" | "off" => Ok(DistCoarseStrategy::None),
            "root" | "root_gather" | "gather" => Ok(DistCoarseStrategy::RootGather),
            "local" | "local_prototype" | "prototype" | "hybrid" => {
                Ok(DistCoarseStrategy::LocalPrototype)
            }
            "superlu_dist" | "superludist" => Ok(DistCoarseStrategy::SuperLuDist),
            other => Err(KError::InvalidInput(format!(
                "invalid dist coarse strategy: {other}"
            ))),
        }
    }
}