# XAct.jl (sxAct)

High-performance Julia implementation of the xAct tensor algebra suite for General Relativity.

## Core Assertion
sxAct provides a modern, open-source, and verified alternative to the Wolfram Language xAct suite, enabling high-performance tensor calculus in both Julia and Python.

## Technical Stack
- **Core**: Julia (`XAct` module bundling XCore, XPerm, XTensor, XInvar, and TExprLayer)
- **Engine**: Butler-Portugal canonicalization algorithm
- **Python Wrapper**: `xact-py` (import as `xact`, backed by `juliacall`)
- **Verification**: `sxact` (Python parity testing framework)
- **Oracle**: Dockerized Wolfram Engine (for parity checks)

## Key Patterns
- **Stateful Registry**: Manifolds and Tensors are registered globally in a session.
- **TExpr Layer**: A typed expression layer for Julia/Python that validates slot counts and manifold membership at construction time.
- **Rosetta Stone**: Direct mapping from Wolfram `xAct` syntax to Julia/Python.
- **Verification-First**: Every core operation is parity-tested against the Wolfram Oracle.

## Repository Structure
- `src/`: Julia core implementation (`src/XAct.jl` is the main module entry point).
- `packages/xact-py/`: Python wrapper package.
- `packages/sxact/`: Verification and migration tooling (`xact-test`, adapters, normalization, comparison).
- `tests/`: Multi-tier test suite (TOML-based parity tests).
- `docs/src/`: Documentation sources for `Documenter.jl`.
- `oracle/`: Docker and server configuration for the Wolfram Engine bridge.

## Documentation Map
- `docs/src/index.md`: Overview and Rosetta Stone.
- `docs/src/getting-started.md`: Quick start for Julia and Python.
- `docs/src/concepts.md`: Symbol registry and TExpr concepts.
- `docs/src/status.md`: Feature completion matrix.
- `docs/src/api-julia.md` / `docs/src/api-python.md`: API references.
- `docs/src/verification-tools.md`: How the parity testing works.

## LLM Guidance
- Prefer the **Typed Expression API** (`TExpr`) for new examples.
- Use `using XAct` in Julia and `import xact` in Python.
- Use `reset_state!()` in Julia and `xact.reset()` in Python for clean session starts.
- Refer to `docs/src/status.md` for implemented vs. planned features.
- Verification tests use TOML files in `tests/` which are processed by `uv run xact-test`.
