chacana

The top-level chacana module exposes the public API.

chacana

Chacana -- a tensor calculus DSL with static type checking.

GlobalContext(manifolds: dict[str, ManifoldDecl] = dict(), tensors: dict[str, TensorDecl] = dict(), active_metric: str | None = None, strategy: dict[str, object] = dict(), sparsity: dict[str, SparsityDecl] = dict(), perturbations: dict[str, PerturbationDecl] = dict()) dataclass

ChacanaParseError

Bases: ChacanaError

Raised when the input expression cannot be parsed.

ChacanaTypeError

Bases: ChacanaError

Raised when type checking fails (index mismatch, rank error, etc.).

parse(expr: str, *, context: GlobalContext | None = None) -> dict[str, Any]

Parse a tensor expression and optionally type-check it.

Applies Unicode NFC normalization and rejects out-of-scope characters before parsing. Also rejects nested symmetrization after parsing.

Returns a MathJSON-style dict (ValidationToken.to_dict()).

Source code in src/chacana/__init__.py

def parse(expr: str, *, context: GlobalContext | None = None) -> dict[str, Any]:
    """Parse a tensor expression and optionally type-check it.

    Applies Unicode NFC normalization and rejects out-of-scope characters
    before parsing. Also rejects nested symmetrization after parsing.

    Returns a MathJSON-style dict (ValidationToken.to_dict()).
    """
    from arpeggio import NoMatch

    expr = normalize_input(expr)
    try:
        tree = parse_and_validate(expr)
    except NoMatch as e:
        raise ChacanaParseError(str(e)) from e

    token = parse_to_ast(tree)
    check(token, context)
    return token.to_dict()

check(token: ValidationToken, ctx: GlobalContext | None = None) -> ValidationToken

Run all type checks on a ValidationToken. Returns the token if valid.

Source code in src/chacana/checker.py

def check(token: ValidationToken, ctx: GlobalContext | None = None) -> ValidationToken:
    """Run all type checks on a ValidationToken. Returns the token if valid."""
    _check_contraction(token, ctx)
    _check_free_index_invariance(token, ctx)
    _check_symmetry(token, ctx)
    if ctx is not None:
        _check_rank(token, ctx)
        _check_operators(token, ctx)
    return token

load_context(source: str | Path) -> GlobalContext

Load a GlobalContext from a TOML file path or string.

Prefer :func:load_context_file or :func:load_context_string for unambiguous loading.

Source code in src/chacana/context.py

def load_context(source: str | Path) -> GlobalContext:
    """Load a GlobalContext from a TOML file path or string.

    Prefer :func:`load_context_file` or :func:`load_context_string` for
    unambiguous loading.
    """
    import warnings

    if isinstance(source, Path):
        return load_context_file(source)
    if "\n" not in source and Path(source).is_file():
        warnings.warn(
            "load_context() auto-detected a file path from a string argument. "
            "Use load_context_file() instead for explicit file loading.",
            DeprecationWarning,
            stacklevel=2,
        )
        return load_context_file(source)
    return load_context_string(source)