CI and maintanence files

Author: youknowone

.github/workflows/rust.yml

@@ -11,24 +11,26 @@ env:
 
 jobs:
   build:
-    name: Build and test
+    name: Build and test (${{ matrix.os }})
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
-        os: [
-          ubuntu-latest,
-          windows-latest,
-          macos-latest,
-        ]
+        os: [ubuntu-latest, windows-latest, macos-latest]
         rust: [stable]
+        include:
+          - os: ubuntu-latest
+            features: complex
+          - os: windows-latest
+            features: complex
+          - os: macos-latest
+            features: complex,mul_add
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: "3.13"
-        check-latest: true
+        python-version: "3.14"
     - name: Setup Rust
       uses: actions-rs/toolchain@v1
       with:
@@ -37,13 +39,9 @@ jobs:
         override: true
     - name: Build
       run: cargo build --verbose
-    - name: Run tests
-      if: matrix.os != 'macos-latest'
-      run: cargo test --verbose && cargo test --release --verbose
-    - name: Run tests with FMA (macOS)
-      if: matrix.os == 'macos-latest'
-      run: cargo test --verbose --features mul_add && cargo test --release --verbose --features mul_add
     - name: Run tests with num-bigint
-      run: cargo test --verbose --features num-bigint
+      run: cargo test --verbose --features ${{ matrix.features }},num-bigint
+    - name: Run tests with num-bigint (Release)
+      run: cargo test --verbose --features ${{ matrix.features }},num-bigint --release
     - name: Run tests with malachite-bigint
-      run: cargo test --verbose --features malachite-bigint
+      run: cargo test --verbose --features ${{ matrix.features }},malachite-bigint

.python-version

@@ -0,0 +1 @@
+3.14

AGENTS.md

@@ -0,0 +1,195 @@
+# pymath Agent Guidelines
+
+This project is a strict port of CPython's math and cmath modules to Rust.
+
+## Core Principle
+
+**Every function must match CPython exactly** - same logic, same special case handling, same error conditions.
+
+- `math` module → `Modules/mathmodule.c`
+- `cmath` module → `Modules/cmathmodule.c`
+
+## Porting Rules
+
+### 1. Use Existing Helpers
+
+CPython uses helpers like `math_1`, `math_2`, `FUNC1`, `FUNC2`, etc. We have Rust equivalents:
+
+| CPython | Rust |
+|---------|------|
+| `FUNC1(name, func, can_overflow, ...)` | `math_1(x, func, can_overflow)` |
+| `FUNC2(name, func, ...)` | `math_2(x, y, func)` |
+| `m_log`, `m_log10`, `m_log2` | Same names in `exponential.rs` |
+
+If a function uses a helper in CPython, use the corresponding helper here.
+
+### 2. Create Missing Helpers
+
+If CPython has a helper we don't have yet, implement it. Examples:
+- `math_1_fn` for Rust function pointers (vs C function pointers)
+- Special case handlers for specific functions
+
+### 3. Error Handling
+
+CPython sets `errno` and calls `is_error()`. We return `Result` directly:
+
+```rust
+// CPython:
+errno = EDOM;
+if (errno && is_error(r, 1)) return NULL;
+
+// Rust:
+return Err(crate::Error::EDOM);
+```
+
+**Never use `set_errno(libc::EDOM)` or similar** - just return `Err()` directly.
+The only valid `set_errno` call is `set_errno(0)` to clear errno before libm calls.
+
+### 4. Special Cases
+
+CPython has explicit special case handling for IEEE specials (NaN, Inf, etc.). Copy this logic exactly:
+
+```rust
+// Example from pow():
+if !x.is_finite() || !y.is_finite() {
+    if x.is_nan() {
+        return Ok(if y == 0.0 { 1.0 } else { x }); // NaN**0 = 1
+    }
+    // ... more special cases
+}
+```
+
+### 5. Reference CPython Source
+
+Always check CPython source in the `cpython/` directory:
+
+**For math module** (`Modules/mathmodule.c`):
+- Function implementations
+- Helper macros (`FUNC1`, `FUNC1D`, `FUNC2`)
+- Special case comments
+- Error conditions
+
+**For cmath module** (`Modules/cmathmodule.c`):
+- `special_type()` enum and function
+- 7x7 special value tables (e.g., `tanh_special_values`)
+- `SPECIAL_VALUE` macro usage
+- Complex-specific error handling
+
+### 6. Fused Multiply-Add (mul_add)
+
+For bit-exact matching with CPython, use `crate::mul_add(a, b, c)` instead of `a * b + c` in specific cases.
+
+**Why this matters**: CPython compiled with clang on macOS may use FMA (fused multiply-add) instructions for expressions like `1.0 + x * x`. FMA computes `a * b + c` in a single operation without intermediate rounding, which can produce results that differ by 1-2 ULP from separate multiply and add operations.
+
+**When to use `mul_add`**:
+- Expressions of the form `a * b + c` or `c + a * b` in complex math functions
+- Especially in formulas like `1.0 + x * x` → `mul_add(x, x, 1.0)`
+
+**Example** (from `c_tanh`):
+```rust
+// Wrong - may differ from CPython by 1-2 ULP
+let denom = 1.0 + txty * txty;
+let r_re = tx * (1.0 + ty * ty) / denom;
+
+// Correct - matches CPython exactly
+let denom = mul_add(txty, txty, 1.0);
+let r_re = tx * mul_add(ty, ty, 1.0) / denom;
+```
+
+**Example** (from `c_asinh`):
+```rust
+// mul_add for cross-product calculations
+let r_re = m::asinh(mul_add(s1.re, s2.im, -(s2.re * s1.im)));
+let r_im = m::atan2(z.im, mul_add(s1.re, s2.re, -(s1.im * s2.im)));
+```
+
+**Example** (from `c_atanh`):
+```rust
+// mul_add for squared terms
+let one_minus_re = 1.0 - z.re;
+let r_re = m::log1p(4.0 * z.re / mul_add(one_minus_re, one_minus_re, ay * ay)) / 4.0;
+let r_im = -m::atan2(-2.0 * z.im, mul_add(one_minus_re, 1.0 + z.re, -(ay * ay))) / 2.0;
+```
+
+**Feature flag**: The `mul_add` feature controls whether hardware FMA is used:
+
+- `mul_add` enabled: Uses `f64::mul_add()` (hardware FMA instruction)
+- `mul_add` disabled (default): Falls back to `a * b + c` (separate operations)
+
+Note: macOS CI always enables `mul_add` because CPython on macOS uses FMA.
+
+**How to identify missing mul_add usage**:
+1. If a test fails with 1-2 ULP difference
+2. Look for `a * b + c` or `c + a * b` patterns in the failing function
+3. Replace with `mul_add(a, b, c)` and re-test
+
+### 7. Platform-specific sincos (macOS, cmath only)
+
+On macOS, Python's cmath module uses Apple's `__sincos_stret` function, which computes sin and cos together with slightly different results than calling them separately (up to 1 ULP difference).
+
+For bit-exact matching on macOS, use `m::sincos(x)` which returns `(sin, cos)` tuple:
+
+```rust
+// Instead of:
+let sin_x = m::sin(x);
+let cos_x = m::cos(x);
+
+// Use:
+let (sin_x, cos_x) = m::sincos(x);
+```
+
+Required in cmath functions that use both sin and cos of the same angle:
+
+- `cosh`, `sinh` - for the imaginary argument
+- `exp` - for the imaginary argument
+- `rect` - for the phi angle
+
+On non-macOS platforms, `m::sincos(x)` falls back to calling sin and cos separately.
+
+## Testing
+
+### EDGE_VALUES
+
+All float functions must be tested with `crate::test::EDGE_VALUES` which includes:
+- Zeros: `0.0`, `-0.0`
+- Infinities: `INFINITY`, `NEG_INFINITY`
+- NaNs: `NAN`, `-NAN`, and NaN with different payload
+- Subnormals
+- Boundary values: `MIN_POSITIVE`, `MAX`, `MIN`
+- Large values near infinity
+- Trigonometric special values: `PI`, `PI/2`, `PI/4`, `TAU`
+
+### Error Type Verification
+
+Tests must verify both:
+1. Correct values for Ok results
+2. Correct error types (EDOM vs ERANGE) for Err results
+
+Python `ValueError` → `Error::EDOM`
+Python `OverflowError` → `Error::ERANGE`
+
+## File Structure
+
+### Core
+- `src/lib.rs` - Root module, `mul_add` function
+- `src/err.rs` - Error types (EDOM, ERANGE)
+- `src/test.rs` - Test helpers, `EDGE_VALUES`, `EDGE_INTS`
+
+### System libm bindings
+- `src/m_sys.rs` - Raw FFI declarations (`extern "C"`)
+- `src/m.rs` - Safe wrappers, platform-specific `sincos`
+
+### math module
+- `src/math.rs` - Main module, `math_1`, `math_2` helpers, `hypot`, constants
+- `src/math/exponential.rs` - exp, log, pow, sqrt, cbrt, etc.
+- `src/math/trigonometric.rs` - sin, cos, tan, asin, acos, atan, etc.
+- `src/math/misc.rs` - frexp, ldexp, modf, fmod, copysign, isclose, ulp, etc.
+- `src/math/gamma.rs` - gamma, lgamma, erf, erfc
+- `src/math/aggregate.rs` - fsum, prod, sumprod, dist (vector operations)
+- `src/math/integer.rs` - gcd, lcm, isqrt, comb, perm, factorial (requires `_bigint` feature)
+
+### cmath module (requires `complex` feature)
+- `src/cmath.rs` - Main module, `special_type`, `special_value!` macro, shared constants
+- `src/cmath/exponential.rs` - sqrt, exp, log, log10
+- `src/cmath/trigonometric.rs` - sin, cos, tan, sinh, cosh, tanh, asin, acos, atan, asinh, acosh, atanh
+- `src/cmath/misc.rs` - phase, polar, rect, abs, isfinite, isnan, isinf, isclose