Warning
All code in this repository is generated by AI. Use at your own caution. It was built under strict engineering practices but is not warranted to be absolutely correct. The only way to validate its correctness is to use it and identify failures. This repository is in an experimental phase and was meant to explore how to use AI to develop scientific software. Feel free to open issues; pull requests are momentarily closed until I (or industry, communities) figure out a way to manage them.
XAct.jl is a native Julia port of the xAct tensor algebra suite for general relativity, originally developed by José M. Martín-García and collaborators for Wolfram Mathematica. This project rewrites the xAct engine in pure Julia for performance, composability, and open access without a Mathematica license.
For the canonical newcomer path, follow:
- Installation — set up Julia, Python, or the verification stack
- Getting Started — first successful tensor workflow in Julia or Python
- Typed Expressions (TExpr) — recommended expression-building API
- Tutorials and notebooks — longer guided examples
using XAct
reset_state!()
def_manifold!(:M, 4, [:a, :b, :c, :d])
def_tensor!(:T, ["-a", "-b"], :M; symmetry_str="Symmetric[{-a,-b}]")
@indices M a b c d
T_h = tensor(:T)
ToCanonical(T_h[-b,-a] - T_h[-a,-b]) # returns "0"The typed API (@indices, tensor(), T_h[...]) validates slot counts and manifold
membership at construction time. The string API (ToCanonical("T[-b,-a] - T[-a,-b]"))
still works everywhere.
Install the published Python wrapper from PyPI with pip install xact-py. On first import, xact-py resolves the Julia package XAct from the Julia registries via juliapkg, then:
import xact
xact.reset()
M = xact.Manifold("M", 4, ["a", "b", "c", "d"])
T = xact.Tensor("T", ["-a", "-b"], M, symmetry="Symmetric[{-a,-b}]")
a, b, c, d = xact.indices(M)
T_h = xact.tensor("T")
xact.canonicalize(T_h[-b,-a] - T_h[-a,-b]) # returns "0"| Name | Kind | Meaning |
|---|---|---|
| Wolfram xAct | Upstream Project | The original tensor algebra suite for Mathematica |
XAct.jl |
Git repository | The repository you clone from GitHub |
XAct.jl / XAct |
Julia package and module | The native Julia tensor algebra engine |
xact-py |
Python package name | The package published to PyPI |
xact |
Python import name | The public Python API you write in code |
sxact |
Python verification framework | The xAct-specific parity-testing, oracle-snapshot, adapter, and Eleguá bridge tooling |
The docs landing page has the same map in the "What is what?" section.
Note
Early adopter stage. XAct.jl has parity-level test coverage against the Wolfram engine (1200+ Julia tests, 900+ Python tests) but has only been used by the author so far. If you try it on a real problem and something breaks, please open an issue — that's the most valuable contribution right now.
| Wolfram xAct | XAct.jl | Status |
|---|---|---|
| xCore, xPerm, xTensor, xCoba, Invar | XCore, XPerm, XTensor, XInvar | Ported |
| xPert (perturbation theory) | In XTensor | Partial — perturb(), PerturbCurvature done |
| xTras (utilities) | In XTensor | Partial — CollectTensors, AllContractions, etc. |
| Spinors, xTerior, Harmonics, TexAct | — | Not yet started |
The engine currently operates on string representations of tensor expressions — every ToCanonical, Contract, Simplify call parses a string, operates, and serializes back. This mirrors the original Wolfram design but is not idiomatic Julia. The TExpr typed layer (@indices, tensor(), T[-a,-b]) adds validated input/output but still serializes internally. Making TExpr the native engine representation is the top priority refactor.
The xact-py package provides a Pythonic API backed by the Julia engine via juliacall, making XAct.jl accessible without writing Julia. For normal use, install the published PyPI release with pip install xact-py; it resolves XAct from the Julia registries on first import. Use packages/xact-py from this repository only if you explicitly need unreleased changes from main.
Examples from the docs are backed by test/julia/xtensor/test_textbook_gr_regressions.jl, which exercises concrete general-relativity checks drawn from the Schwarzschild, FLRW, and Riemann-symmetry notebooks. This suite complements the broader oracle, property, and invariant test layers.
- Julia notebook — open in JupyterLab, Google Colab, or Binder
- Python notebook — open in JupyterLab, Google Colab, or Binder
- Local:
just labto launch JupyterLab
- XAct.jl (Julia): The computational engine — canonicalization, contraction, covariant derivatives, perturbation theory, coordinate components (xCoba), Riemann invariants (Invar). Native rewrite of the Wolfram xAct modules xPerm, xTensor, xCoba, and Invar.
- sxact (Python): Automated parity testing against the Wolfram Engine using TOML test cases and oracle snapshots. It consumes Eleguá for shared validation infrastructure (TOML bridge parsing, live-run isolation, comparison-pipeline composition, and oracle HTTP transport) while retaining xAct-specific adapters, expression builders, comparison layers, and snapshot artifacts.
- Chacana — Tensor calculus DSL with static type checking and a PEG grammar specification. Parses tensor expressions into a MathJSON-style AST. (docs)
- Eleguá — Domain-agnostic, multi-tier test harness for validating mathematical equivalence across symbolic computing systems. (docs)
Full documentation at saxa.xyz/XAct.jl, including the full status and roadmap.
The majority of this codebase was developed with AI assistance using Claude Code, Gemini, and Amp Code. All code is human-reviewed and tested against the Wolfram Engine oracle for mathematical correctness.
XAct.jl is copyright (c) 2024-2026 XAct.jl Contributors and released under the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for the full text.