Skip to main content

Crate kryst

Crate kryst 

Source
Expand description

§kryst

PETSc-like Krylov solvers (KSP) and preconditioners (PC) in Rust.

§PETSc compatibility matrix

§Quick start (serial)

use kryst::prelude::*;
use kryst::matrix::MatShell;
use kryst::algebra::prelude::KrystScalar;
use std::sync::Arc;

let n = 4;
let a = MatShell::<S>::new(n, n, move |x, y| {
    for i in 0..n {
        let mut sum = S::from_real(2.0) * x[i];
        if i > 0 {
            sum -= x[i - 1];
        }
        if i + 1 < n {
            sum -= x[i + 1];
        }
        y[i] = sum;
    }
});
let a = Arc::new(a) as Arc<dyn LinOp<S = S>>;
let b = vec![S::from_real(1.0); n];
let mut x = vec![S::zero(); n];

let mut ksp = KspContext::new();
ksp.set_type(SolverType::Gmres)?;
ksp.set_pc_type(PcType::None, None)?;
ksp.set_operators(a, None);
ksp.setup()?;
let stats = ksp.solve(&b, &mut x)?;
println!("reason={:?} residual={:.3e}", stats.reason, stats.final_residual);

§Lifecycle

  1. set_type / set_pc_type / set_from_options
  2. set_operators(Amat, Pmat)
  3. setup() (idempotent; reuses structure/values when possible)
  4. solve(b, x) (may call setup() automatically if needed)

§Reuse model

  • LinOp::structure_id changes when the sparsity pattern or dimensions change.
  • LinOp::values_id changes when only numeric values change.
  • StructureId(0) / ValuesId(0) mean “unknown” and force conservative rebuilds.
  • Wrappers like CsrOp / DenseOp expose mark_structure_changed and mark_values_changed helpers.

§MPI communicator rules

  • KspContext is bound to the operator communicator when operators are set.
  • try_set_operators checks communicator congruence and dimension congruence.
  • try_set_operators_with_comm wraps operators with an explicit communicator.
  • Communicators must be IDENT or CONGRUENT (MPI_Comm_compare semantics).

§Feature flags

FeatureEnablesNotes
mpiMPI communication backendRequires MPI installed; MPI examples run via mpirun
complexComplex scalar S (Complex64)Classical and pipelined GMRES/FGMRES variants are supported
backend-faerDense/CSR backends and most PCsDefault feature

S is the internal scalar alias and R is its real partner. In real builds S = R = f64. In complex builds S = Complex64 and R = f64.

§Next steps

  • docs/communicators.md for communicator details
  • docs/petsc_mapping.md for PETSc to kryst mapping
  • examples/ for runnable demos

Re-exports§

pub use crate::algebra::R;
pub use crate::algebra::S;
pub use crate::config::options::KspOptions;
pub use crate::config::options::PcOptions;
pub use crate::context::KspContext;
pub use crate::context::ksp_context::SolverType;
pub use crate::context::pc_context::PcType;
pub use crate::error::KError;
pub use crate::matrix::LinOp;
pub use crate::parallel::Comm;
pub use crate::parallel::UniverseComm;
pub use crate::preconditioner::PcSide;
pub use crate::preconditioner::Preconditioner;
pub use crate::utils::convergence::ConvergedReason;
pub use crate::utils::convergence::SolveStats;

Modules§

algebra
Basic numeric traits and operations used throughout the crate.
config
context
KSP/PC context types and factories.
core
error
matrix
Matrix module: dense and sparse matrix types and traits.
parallel
Parallel communicators and reduction helpers.
preconditioner
Preconditioners
prelude
Daily-driver re-exports for kryst.
solver
Solver traits and implementations.
utils
Utility modules for logging, convergence checks, graph coloring, reordering, and profiling.

Macros§

assert_s_close
Convenience macro: scalar close with defaults
assert_vec_close
Convenience macro: vector close with defaults
invariantinvariants
pc_loglogging
time_stage
Macro for timing a code block with automatic stage guard creation.
with_monitoring
Conditionally execute monitoring code only when monitoring is enabled.
with_profiling
Conditionally execute profiling code only when profiling is enabled.