# SageMath Migration Guide

This guide is for SageMath users moving algebra, number theory, symbolic
calculus, and notebook workflows to Kalika.

Official source references used while preparing this guide:

- Sage reference manual: <https://doc.sagemath.org/html/en/reference/>
- Sage symbolic calculus:
  <https://doc.sagemath.org/html/en/reference/calculus/index.html>
- Sage basic rings tutorial:
  <https://doc.sagemath.org/html/en/tutorial/tour_rings.html>

## Workflow Comparison

| SageMath Workflow                   | Kalika Workflow                                                                                       | Notes                                                                           |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| One large `sage.all` namespace      | Import the package that owns the domain                                                               | Kalika makes package boundaries visible.                                        |
| Parent/ring-driven coercion         | Explicit constructors such as `rationalMatrix`, `RationalField`, `PolynomialRing`, `createPrimeField` | Prefer explicit data construction at module boundaries.                         |
| Symbolic expressions for everything | SDK for CAS, domain packages for exact structures                                                     | Avoid using generic expressions for polynomial/ring-heavy workloads.            |
| Notebook cells with implicit state  | Kalika notebooks plus explicit SDK clients and dependency locks                                       | Use notebook provenance and lockfiles for reproducibility.                      |
| Built-in plotting from objects      | `@kalika/renderer` with domain results                                                                | Rendering is a separate package, not a method on every object.                  |
| Sage categories                     | `@kalika/category-theory`                                                                             | Use category objects and morphisms directly when categorical structure matters. |

## Quick Mapping

| SageMath                          | Kalika Target                                                 | Notes                                                                 |
| --------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------- |
| `var("x")`, symbolic calculus     | `@kalika/sdk` symbolic calls or `@kalika/notebooks` CAS cells | SDK calls are explicit and metadata-bearing.                          |
| `diff(f, x)`                      | `sdk.differentiate(f, "x")`                                   | Same computational intent, different result wrapper.                  |
| `integrate(f, x)`                 | `sdk.integrate(f, "x")`                                       | Route specialized integrals to analysis/numerical packages as needed. |
| `matrix(QQ, rows)`                | `rationalMatrix(rows)`                                        | Exact rational matrix workflows live in `@kalika/algebra`.            |
| `M.det()`, `M.rref()`, `M.rank()` | `determinant`, `reducedRowEchelonForm`, `rank`                | Functional API rather than object methods.                            |
| `PolynomialRing(QQ, "x")`         | `new PolynomialRing(RationalField, "x")`                      | Keep coefficient rings explicit.                                      |
| `GF(p)`                           | `createPrimeField(p)`                                         | Prime-field arithmetic is in `@kalika/algebra`.                       |
| `factor(n)`, `is_prime(n)`        | `factorInteger`, `isPrime`                                    | Number theory is in `@kalika/number-theory`.                          |
| `EllipticCurve(...)`              | `shortWeierstrassCurve(...)`                                  | Arithmetic-geometry workflows live in `@kalika/number-theory`.        |
| `Category`, `Hom`, functors       | `createCategory`, `morphism`, `functor`                       | Category workflows are explicit objects.                              |

## Exact Algebra Pattern

```ts
import {
  PolynomialRing,
  RationalField,
  determinant,
  rank,
  rationalMatrix,
  reducedRowEchelonForm,
} from '@kalika/algebra';

const matrix = rationalMatrix([
  [1, 2, 3],
  [2, 4, 7],
  [1, 0, 1],
]);

const det = determinant(matrix);
const rref = reducedRowEchelonForm(matrix);
const matrixRank = rank(matrix);

const qx = new PolynomialRing(RationalField, ['x']);
const x = qx.variable(0);
const polynomial = x.mul(x).add(qx.one());

console.log(det, rref.pivotColumns, matrixRank, polynomial);
```

## Number Theory Pattern

```ts
import {
  factorInteger,
  isPrime,
  shortWeierstrassCurve,
} from '@kalika/number-theory';

const factors = factorInteger(2n ** 61n - 1n);
const prime = isPrime(2n ** 61n - 1n);
const curve = shortWeierstrassCurve(-1n, 0n);

console.log({ factors, prime, curve });
```

## Migration Checklist

- Replace `from sage.all import *` with explicit Kalika package imports.
- Identify whether each Sage object is symbolic, exact algebraic, numeric,
  geometric, categorical, or notebook infrastructure.
- Port exact structures before symbolic convenience wrappers; this preserves
  ring and field intent.
- Replace method chaining (`M.det()`) with functional calls where Kalika APIs
  expose plain data structures.
- Use `@kalika/notebooks` dependency locks and provenance when migrating Sage
  notebooks used for publication or collaboration.
