Skip to main content

auslander/
lib.rs

1//! Finite-dimensional basic algebras `kQ/I` over a checked prime field, and
2//! their finite-dimensional right modules.
3//!
4//! `I` is an admissible ideal presented by uniform relations. Each relation is
5//! a k-linear combination of parallel paths. Every algebra comes from one
6//! pipeline: completion rewrites the relations into a reduced Groebner basis
7//! and emits a certificate. An independent verifier checks that certificate
8//! before the algebra is built.
9//!
10//! Two conventions are fixed crate-wide. Modules are right modules, written
11//! with row vectors. Paths compose left to right: `a·b` means first `a`, then
12//! `b`, and `M(a·b) = M(a) M(b)`.
13//!
14//! Partiality is typed. A dimension known only from below is
15//! `Bounded::AtLeast`. A resolution prefix that runs out of budget ends in
16//! `ResolutionEnd::Cut` with the next syzygy known to be nonzero. Nothing
17//! truncates silently.
18//!
19//! Derived classification sorts a finite family over one field into derived
20//! equivalence classes. [`derived_invariant`] computes checked invariants of
21//! one algebra, and a [`derived_invariant::DerivedInequivalenceWitness`]
22//! separates two algebras. [`equivalence_discovery`] walks mutations, and
23//! [`algebra_isomorphism`] matches each recovered target against the family.
24//! [`derived_classification::classify_derived`] combines both sides: every
25//! pair of members is merged, separated, or typed
26//! [`derived_classification::UnresolvedPair`].
27//!
28//! Each portable artifact kind has its own parser, verifier, and error type,
29//! and [`artifact`] selects one by header. A kind lives in a top-level
30//! `*_artifact` module, or next to the type it serializes: [`census`],
31//! [`batch_stream`], and [`derived_classification`].
32
33macro_rules! accessor_methods {
34    ($($(#[$attr:meta])* $vis:vis $name:ident($($argument:ident: $argument_type:ty),*) -> $output:ty = |$receiver:ident| $value:expr;)+) => {$(
35        $(#[$attr])*
36        #[inline]
37        $vis fn $name(&self, $($argument: $argument_type),*) -> $output { let $receiver = self; $value }
38    )+};
39}
40
41macro_rules! display_error {
42    (error $type:ty { $($body:tt)* }) => {
43        display_error!($type { $($body)* });
44        impl std::error::Error for $type {}
45    };
46    ($type:ty { $($pattern:pat => $format:literal $(, $argument:expr)*;)+ }) => {
47        impl std::fmt::Display for $type {
48            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
49                match self { $($pattern => write!(f, $format $(, $argument)*),)+ }
50            }
51        }
52    };
53}
54
55macro_rules! from_variants {
56    ($target:ty { $($source:ty => $variant:ident),+ $(,)? }) => {$ (
57        impl From<$source> for $target {
58            fn from(error: $source) -> Self { Self::$variant(error) }
59        }
60    )+};
61}
62
63/// Maps [`portable::PortableError`] onto an error with `Syntax` and
64/// `ParseLimit` variants of the same fields. With `header`, also maps
65/// `portable::HeaderMismatch` onto `Schema`, `Kind`, and `Engine` variants.
66macro_rules! from_portable_error {
67    ($target:ty, header) => {
68        from_portable_error!($target);
69        impl From<$crate::portable::HeaderMismatch> for $target {
70            fn from(error: $crate::portable::HeaderMismatch) -> Self {
71                match error {
72                    $crate::portable::HeaderMismatch::Schema { found } => Self::Schema { found },
73                    $crate::portable::HeaderMismatch::Kind { found } => Self::Kind { found },
74                    $crate::portable::HeaderMismatch::Engine { found } => Self::Engine { found },
75                }
76            }
77        }
78    };
79    ($target:ty) => {
80        impl From<$crate::portable::PortableError> for $target {
81            fn from(error: $crate::portable::PortableError) -> Self {
82                match error {
83                    $crate::portable::PortableError::Syntax { byte, message } => {
84                        Self::Syntax { byte, message }
85                    }
86                    $crate::portable::PortableError::ParseLimit { path, used, limit } => {
87                        Self::ParseLimit { path, used, limit }
88                    }
89                }
90            }
91        }
92    };
93}
94
95macro_rules! error_source {
96    ($error:ty { $($pattern:pat => $source:expr),+ $(,)? }) => {
97        impl std::error::Error for $error {
98            fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
99                match self { $($pattern => $source,)+ }
100            }
101        }
102    };
103}
104
105macro_rules! debug_fields {
106    ($(#[$attr:meta])* $type:ty |$this:ident| { $($field:literal => $value:expr;)+ }) => {
107        $(#[$attr])*
108        impl std::fmt::Debug for $type {
109            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
110                let $this = self;
111                f.debug_struct(stringify!($type))$(.field($field, &$value))+.finish()
112            }
113        }
114    };
115}
116
117macro_rules! verify_methods {
118    ($visibility:vis, $prologue:block, $(#[$attr:meta])* |$this:ident, $context:ident| $body:block) => {
119        $(#[$attr])*
120        pub fn verify(&$this) -> bool {
121            $this.verify_with_context(&VerificationContext::new())
122        }
123        $visibility fn verify_with_context(&$this, $context: &VerificationContext) -> bool {
124            $prologue
125            $body
126        }
127    };
128}
129
130macro_rules! binary_outcome_accessors {
131    (
132        $positive:ident, $negative:ident,
133        $positive_method:ident -> $positive_ty:ty = |$positive_binding:ident| $positive_ref:expr,
134        $negative_method:ident -> $negative_ty:ty = |$negative_binding:ident| $negative_ref:expr,
135        $flag:ident,
136        $into:ident -> $into_ty:ty = |$into_binding:ident| $into_value:expr;
137        flag = $flag_doc:literal;
138        positive = $positive_doc:literal;
139        negative = $negative_doc:literal;
140        into = $into_doc:literal;
141    ) => {
142        #[doc = $flag_doc]
143        #[inline]
144        pub fn $flag(&self) -> bool {
145            matches!(self, Self::$positive(_))
146        }
147        optional_accessors! {
148            #[doc = $positive_doc]
149            pub $positive_method() -> &$positive_ty = Self::$positive($positive_binding) => $positive_ref;
150            #[doc = $negative_doc]
151            pub $negative_method() -> &$negative_ty = Self::$negative($negative_binding) => $negative_ref;
152        }
153        #[doc = $into_doc]
154        #[inline]
155        pub fn $into(self) -> Option<$into_ty> {
156            match self {
157                Self::$positive($into_binding) => Some($into_value),
158                _ => None,
159            }
160        }
161    };
162}
163
164macro_rules! binary_power {
165    ($base:expr, $one:expr, $exponent:expr, |$left:ident, $right:ident| $product:expr) => {{
166        let mut base = $base;
167        let mut accumulator = $one;
168        let mut exponent = $exponent;
169        while exponent > 0 {
170            if exponent & 1 == 1 {
171                let ($left, $right) = (&accumulator, &base);
172                accumulator = $product;
173            }
174            let ($left, $right) = (&base, &base);
175            base = $product;
176            exponent >>= 1;
177        }
178        accumulator
179    }};
180}
181
182macro_rules! nominal_key {
183    ($type:ty, |$left:ident, $right:ident| $equal:expr, |$this:ident| $address:expr) => {
184        impl PartialEq for $type {
185            fn eq(&self, other: &$type) -> bool {
186                let ($left, $right) = (self, other);
187                $equal
188            }
189        }
190        impl Eq for $type {}
191        impl std::hash::Hash for $type {
192            fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
193                let $this = self;
194                std::hash::Hash::hash(&$address, state);
195            }
196        }
197    };
198}
199
200macro_rules! optional_accessors {
201    ($($(#[$attr:meta])* $vis:vis $name:ident() -> $output:ty = $pattern:pat => $value:expr;)+) => {$(
202        $(#[$attr])*
203        #[inline]
204        $vis fn $name(&self) -> Option<$output> {
205            match self { $pattern => Some($value), _ => None }
206        }
207    )+};
208}
209
210macro_rules! let_or_false {
211    ($pattern:pat = $value:expr) => {
212        let $pattern = $value else { return false };
213    };
214}
215
216macro_rules! verify_guard {
217    ($condition:expr) => {
218        if !$condition {
219            return false;
220        }
221    };
222}
223
224pub mod algebra;
225pub mod algebra_isomorphism;
226pub mod almost_split;
227pub mod approx;
228pub mod ar;
229pub mod arquiver;
230pub mod artifact;
231pub mod atlas;
232pub mod atlas_artifact;
233pub mod basic;
234pub mod batch;
235pub mod batch_stream;
236pub mod catalog_coordinates;
237pub mod census;
238pub mod certificate;
239pub mod completion;
240pub mod complex;
241pub mod complex_target;
242pub(crate) mod context;
243pub mod control;
244pub mod decompose;
245pub mod derived;
246pub mod derived_artifact;
247pub mod derived_classification;
248pub mod derived_hom;
249pub mod derived_invariant;
250pub mod derived_transport;
251pub mod dynkin;
252pub mod endo;
253pub mod enumerate;
254pub mod equivalence_discovery;
255pub mod equivalence_edge;
256pub mod ext;
257pub mod extalgebra;
258pub mod family;
259pub mod field;
260pub mod gentle;
261pub mod higher;
262pub mod hochschild;
263pub mod hom;
264pub mod homotopy;
265pub mod homspace;
266pub mod indec;
267pub mod injective;
268pub mod interface;
269pub mod iso;
270pub mod linalg;
271pub mod module;
272pub mod monomial;
273pub mod mutation;
274pub mod opposite;
275pub mod order;
276pub mod perfect;
277pub(crate) mod portable;
278pub mod profile;
279pub mod quiver;
280pub mod radical;
281pub mod relation;
282pub mod resolution;
283pub mod sequence;
284pub mod supporttau;
285pub mod target;
286pub mod taugraph;
287pub mod taurigid;
288pub mod theorem_artifact;
289pub mod tilting;
290pub mod tilting_complex;
291pub mod verify;