yui-core 0.5.0

Core Library for YUI
Documentation 
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

# yui-core

[![crates.io](https://img.shields.io/crates/v/yui-core.svg)](https://crates.io/crates/yui-core)
[![docs.rs](https://docs.rs/yui-core/badge.svg)](https://docs.rs/yui-core)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

The foundational crate of the [`yui`](https://github.com/taketo1024/yui) workspace: algebraic trait hierarchy, concrete numeric types, polynomials, linear combinations, and supporting algorithms / extension traits.

## Layout

```text
src/
├── abst/    — algebraic trait hierarchy: Ring, EucRing, Field, RMod, ...
├── conc/    — concrete instantiations: Ratio, FF, Sign, Poly, Lc, BitSeq
├── ext/     — extension traits: IteratorExt, RangeExt, IntoDigits, ...
├── algo/    — TopSort, UnionFind, KeyedUnionFind, rep_comb
└── util/    — formatting, data-dir resolution, thread-safe counter
```

## Algebraic hierarchy

The traits in `abst/` form the algebraic supertrait stack that everything else is generic over:

```text
              MathType                  (basic shape + math_symbol())
                 │
           ┌─────┴─────┐
           ↓           ↓
         AddMon       Mon               (zero, +)        (one, ×)
           ↓           │
         AddGrp        │                (negation)
           └─────┬─────┘
                 ↓
               Ring     ──────►  RMod   (module over a ring R)
                 ↓
              EucRing                   (gcd, div_rem)
                 ↓
               Field                    (every nonzero invertible)
```

Arrows `↓` denote supertrait inheritance: `Ring: AddGrp + Mon`, `EucRing: Ring`, etc.
`RMod` takes its scalar ring `R: Ring` as an associated type, not a supertrait.

A typical `where`-clause:

```rust,ignore
fn foo<R>(x: &R) -> R
where R: Ring, for<'x> &'x R: RingOps<R>
{ ... }
```

The `for<'x>` HRTB on the reference impl is required throughout; the [`auto_impl_ops`](https://crates.io/crates/auto-impl-ops) crate derives the four `Add`/`Mul` reference variants from a single `+=`/`*=`.

## Concrete types

`conc/num/`:
- `IntType` impls for `i32 / i64 / i128 / BigInt`.
- `Ratio<T>` — fractions over a Euclidean ring; `Ratio<i64>` and `Ratio<BigInt>` are the rationals.
- `FF<p>` — finite field 𝔽ₚ for prime `p`. For 𝔽₂, prefer the specialized `FF2` (uses XOR/AND directly on a `bool`).
- `QuadInt<I, D>` — quadratic integers in ℤ\[ω\] for `ω = (1+√D)/2` or `√D`; aliases `GaussInt`, `EisenInt`.
- `Sign` — the multiplicative group `{±1}`, with the `GetSign` trait.

`conc/poly/`:
- `Poly<X, R>` — univariate polynomial. 
- `LPoly<X, R>` — univariate Laurent variant.
- `Poly2`, `Poly3` (fixed arity), `PolyN<X, R>` (multivariate), plus their Laurent variants.

`conc/lc/`:
- `Lc<X, R>` — formal linear combination `Σ rᵢxᵢ` with keys `X: LcKey` and coefficients in `R: Ring`. Elements of the free `R`-module over the key set.

`conc/misc/`:
- `bitseq::BitSeq<I>` — packed sequence of bits over a word `I`, length up to `I::BITS`.
  Aliases `BitSeq8`, `BitSeq16`, `BitSeq32`, `BitSeq64`, `BitSeq128` pin the width.

## Quick example

```rust
use yui_core::num::Ratio;

let a = Ratio::new(1_i64, 2);
let b = Ratio::new(1_i64, 3);
assert_eq!((&a + &b).to_string(), "5/6");
assert_eq!((&a * &b).to_string(), "1/6");
```

## Feature flags

- `serde` — `Serialize`/`Deserialize` for the concrete types.

## License

This library is licensed under the [MIT License](https://opensource.org/licenses/MIT).

---

*This README was generated by [Claude](https://www.anthropic.com/claude).*