Configuration & Guardrails

Phaethon operates across two distinct worlds: the Hybrid Data Schema (parsing and cleaning tabular data) and the Physics Engine (tensor mathematics and dimensional algebra).

The phaethon.config and phaethon.using interfaces act as the unified Control Center for both worlds. They determine how strictly physical laws are enforced, how floating-point anomalies are handled, and how volatile environmental states are injected into calculations.

State Management

Phaethon provides two ways to apply configurations: globally or locally.

Global Configuration

Use phaethon.config() to set the behavior for the entire Python runtime. This is typically done once at the entry point of your application.

import phaethon as ptn

# Set global physics strictness and tolerance
ptn.config(axiom_strictness_level="strict_warn", atol=1e-10)

Contextual Overrides

Use the phaethon.using() context manager to temporarily override settings for a specific block of code. This is thread-safe and perfect for handling isolated, dirty data without affecting the rest of the application.

import phaethon as ptn
import phaethon.units as u

# Temporarily ignore the laws of physics for this calculation
with ptn.using(axiom_strictness_level="ignore"):
    impossible_temp = u.Kelvin(-500)

Axiom Strictness Levels

Physical units in Phaethon are often protected by @axiom.bound (e.g., Temperature cannot drop below 0 Kelvin; Particle Cross-Section Area cannot be negative). The axiom_strictness_level determines how aggressively Phaethon polices these boundaries.

Adjusting this level is highly recommended when dealing with stochastic tensor generation (phaethon.random). Since statistical variance (like Gaussian noise) can naturally generate values that temporarily dip outside absolute physical boundaries, adjusting the strictness level prevents unexpected AxiomViolationError crashes.

Error Handling Policies

When an axiom strictness level determines that a violation must be enforced, the default_on_error parameter dictates exactly how Phaethon neutralizes the threat.

Example Usage:

Even outside of a DataFrame schema, Phaethon's C-Engine intercepts invalid arrays and coerces them at the tensor level.

import phaethon as ptn
import phaethon.units as u

# We use 'coerce' to survive impossible physics
with ptn.using(default_on_error="coerce"):
    # Trying to instantiate Kelvins below Absolute Zero
    temps = u.Kelvin([300.0, -15.0, 250.0])

    print(temps.mag)
    # Output: [300.  nan 250.] (The -15.0 is safely neutralized to NaN)

Floating-Point Tolerances

Because dimensional algebra often involves irrational numbers, constants (e, pi), and complex logarithmic synthesis, direct equality (==) in floating-point physics is dangerous. Phaethon uses built-in tolerances for all equality and comparative operations (<, <=, >, >=).

Example Usage:

import phaethon as ptn
import phaethon.units as u

a = u.Joule(1.000000000000001)
b = u.Joule(1.0)

# Phaethon evaluates them as equal based on the default tolerances
print(a == b) # Output: True

# Tightening the tolerance globally
with ptn.using(atol=1e-16, rtol=1e-16):
    print(a == b) # Output: False

Environmental Context

Physics is rarely static. The value of a currency fluctuates, and the boiling point of water changes with atmospheric pressure. Phaethon allows you to inject dynamic environmental variables at runtime using the context dictionary.

These variables are intercepted by units decorated with @axiom.scale or @axiom.shift.

Example Usage:

import phaethon as ptn
import phaethon.units as u

# Assuming USDollar is scaled against a "usd_to_idr" context
with ptn.using(context={"usd_to_idr": 15500}):
    budget = u.USDollar(10)

    # The algebraic engine intercepts the context variable
    in_rupiah = budget.to(u.IndonesianRupiah)
    print(in_rupiah)
    # Output: 155000.0 IDR

Formatting Shims

These parameters are exclusively used by Phaethon's backend Rust engine to parse raw, dirty strings into valid numerics. They do not affect how physical tensors are rendered as text (__str__) in the Physics Engine. Instead, they are critically important when ingesting messy tabular datasets via the Hybrid Data Schema, allowing Phaethon to correctly interpret European versus American number formats during data extraction and cleaning.