deep_causality_metric 0.2.1

# deep_causality_metric

Metric signature types and sign conventions for Clifford algebras and physics.

## Overview

This crate provides a foundational set of types for working with metric signatures in Clifford algebras Cl(p, q, r), Riemannian geometry, and physics applications.

### Key Features

- **Single Source of Truth**: Consolidates all metric signature logic into one crate
- **Zero Dependencies**: Serves as a foundational leaf crate in the dependency graph
- **Type-Safe Conventions**: Compile-time enforcement of physics sign conventions
- **Cross-Crate Integration**: Enables consistent metric handling across multivector, tensor, topology, and physics crates

## Core Types

| Type | Description |
|------|-------------|
| `Metric` | Core signature enum Cl(p, q, r) |
| `MetricError` | Error type for metric operations |
| `LorentzianMetric` | Trait for convention wrappers |
| `EastCoastMetric` | (-+++) convention newtype |
| `WestCoastMetric` | (+---) convention newtype |

## Sign Conventions

| Convention | Signature | g_{μν} | Used By |
|------------|-----------|--------|---------|
| East Coast | (-+++) | diag(-1,1,1,1) | MTW, GR textbooks |
| West Coast | (+---) | diag(1,-1,-1,-1) | Weinberg, Particle physics |

### Type Aliases

For domain-specific clarity:

| Alias | Target | Domain |
|-------|--------|--------|
| `RelativityMetric` | `EastCoastMetric` | General Relativity |
| `ParticleMetric` | `WestCoastMetric` | Particle Physics |
| `PhysicsMetric` | `RelativityMetric` | Default (GR) |

## Usage

### Basic Metric Operations

```rust
use deep_causality_metric::Metric;

// Create a standard 4D Minkowski metric (West Coast convention)
let minkowski = Metric::Minkowski(4);
assert_eq!(minkowski.dimension(), 4);
assert_eq!(minkowski.sign_of_sq(0), 1);   // time is +1
assert_eq!(minkowski.sign_of_sq(1), -1);  // space is -1

// Get signature tuple (p, q, r)
assert_eq!(minkowski.signature(), (1, 3, 0));

// Create from signature
let euclidean = Metric::from_signature(3, 0, 0);
assert_eq!(euclidean, Metric::Euclidean(3));
```

### Type-Safe Convention Wrappers

```rust
use deep_causality_metric::{EastCoastMetric, WestCoastMetric, LorentzianMetric};

// East Coast convention (-+++) for General Relativity
let east = EastCoastMetric::minkowski_4d();
assert_eq!(east.time_sign(), -1);
assert_eq!(east.space_sign(), 1);
assert!(east.is_east_coast());

// West Coast convention (+---) for Particle Physics
let west = WestCoastMetric::minkowski_4d();
assert_eq!(west.time_sign(), 1);
assert_eq!(west.space_sign(), -1);
assert!(west.is_west_coast());
```

### Convention Conversion

```rust
use deep_causality_metric::{Metric, EastCoastMetric, WestCoastMetric};

// Convert from West Coast to East Coast
let west = Metric::Minkowski(4);
let east = EastCoastMetric::from_west_coast(west).unwrap();

// Convert back
let west_again = WestCoastMetric::from_east_coast(east.into_metric()).unwrap();
```

### Using Type Aliases

```rust
use deep_causality_metric::{RelativityMetric, ParticleMetric, MINKOWSKI_4D};

// For GR code
fn relativistic_calculation(metric: RelativityMetric) {
    // Uses East Coast convention internally
    assert!(metric.is_east_coast());
}

// For particle physics code
fn particle_calculation(metric: ParticleMetric) {
    // Uses West Coast convention internally
    assert!(metric.is_west_coast());
}
```

## Mathematical Background

### Clifford Algebra Signature

A Clifford algebra Cl(p, q, r) over ℝⁿ where n = p + q + r is defined by:

$$e_i \cdot e_j + e_j \cdot e_i = 2g_{ij}$$

where the metric tensor g has:
- p eigenvalues of +1
- q eigenvalues of -1
- r eigenvalues of 0 (degenerate)

### Metric Variants

| Variant | Signature | Example Uses |
|---------|-----------|--------------|
| `Euclidean(n)` | (n, 0, 0) | Standard ℝⁿ |
| `NonEuclidean(n)` | (0, n, 0) | Anti-Euclidean |
| `Minkowski(n)` | (1, n-1, 0) | Spacetime (West Coast) |
| `PGA(n)` | (n-1, 0, 1) | Projective Geometric Algebra |
| `Generic{p,q,r}` | (p, q, r) | General Cl(p,q,r) |
| `Custom{...}` | bitmask | Up to 64 dimensions |

## Feature Flags

| Feature | Default | Description |
|---------|---------|-------------|
| `std` | ✓ | Standard library support |
| `alloc` | ✓ | Allocation support (via std) |

For `no_std` environments, disable default features:

```toml
[dependencies]
deep_causality_metric = { version = "0.1", default-features = false, features = ["alloc"] }
```

## License

MIT License - see [LICENSE](LICENSE) for details.