Metadata-Version: 2.4
Name: PhantomTrace
Version: 0.1.0
Summary: PhantomTrace — a mathematical framework where numbers exist in present or absent states with custom operations to include addition, subtraction, multiplication, division, and erasure.
Author: PhantomTrace Project
License: MIT
Project-URL: Homepage, https://github.com/phantomtrace/phantomtrace
Project-URL: Documentation, https://github.com/phantomtrace/phantomtrace#readme
Project-URL: Issues, https://github.com/phantomtrace/phantomtrace/issues
Keywords: math,calculus,absence,abstract-algebra,number-theory,phantomtrace,dual-state
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file
Dynamic: requires-python

# PhantomTrace

A Python library implementing an experimental mathematical framework where numbers can exist in two states: **present** or **absent**. It defines five operations that interact with these states in consistent, rule-based ways.

Zero is redefined: `0` is not emptiness — it's one absence (`1(0)`). This means every operation has a defined result, including division by zero.

**Read the paper**: [Absence Theory](https://www.academia.edu/150254484/Absence_Theory_Quantified_Absence_and_State_Aware_Arithmetic_within_Domains_of_Reference)

## Installation

```bash
pip install phantomtrace
```

## Quick Start

```python
from absence_calculator import AbsentNumber, add, subtract, multiply, divide, erase, format_result

# Create numbers — present (default) or absent
five = AbsentNumber(5)             # 5 (present)
three_absent = AbsentNumber(3, 1)  # 3(0) (absent)

# Addition — same state combines, mixed state is unresolved
result = add(AbsentNumber(5), AbsentNumber(3))
print(result)  # 8

# Subtraction — equal values cancel to void
result = subtract(AbsentNumber(7), AbsentNumber(7))
print(result)  # void

# Multiplication — states combine (like XOR)
result = multiply(AbsentNumber(5, 1), AbsentNumber(3))
print(result)  # 15(0)

# Erasure — flips the state of the erased portion
result = erase(AbsentNumber(5), AbsentNumber(3))
print(result)  # 2 + 3(0)

# Division by zero — defined! (0 is one absence)
result = divide(AbsentNumber(10), AbsentNumber(1, 1))
print(result)  # 10(0)
```

## Using the Expression Solver

```python
from absence_calculator import solve, format_result

# Parse and solve string expressions
print(format_result(solve("5 + 3")))           # 8
print(format_result(solve("5(0) + 3(0)")))     # 8(0)
print(format_result(solve("7 - 7")))           # void
print(format_result(solve("5(0) * 3")))        # 15(0)
print(format_result(solve("5 erased 3")))      # 2 + 3(0)
print(format_result(solve("5(0)(0)")))         # 5 (double absence = present)

# Zero operations
print(format_result(solve("0 + 0")))           # 2(0) (two absences)
print(format_result(solve("0 * 0")))           # 1 (absence of absence = presence)
print(format_result(solve("10 * 0")))          # 10(0)
print(format_result(solve("10 / 0")))          # 10(0)
```

## Interactive Calculator

After installing, you can run the interactive calculator from the command line:

```bash
phantomtrace
```

Or as a Python module:

```bash
python -m absence_calculator
```

This gives you a `calc >>` prompt where you can type expressions and see results.

## Core Concepts

### Objects and States

An object is a number that has both a **value** and a **state**:
- **Present** (default): Written normally, e.g. `5`. Present quantities reflect the presence of a given unit of interest. (e.g. if the unit is a cat, then 5 represents 5 cats that are there or in a present state)
- **Absent**: Written with `(0)`, e.g. `5(0)` — think of it as `5 * 0`. Absent quantities reflect the absence of a given unit of interest. (e.g. if the unit is a phone, then 5(0) represents 5 phones that are not currently there but are still considered for computation)

### Absence
  
- **Zero**: `0` is not emptiness, it's one absence (`1(0) = 1 * 0 = 0`)
- **Absence of absence** returns to present: `5(0)(0) = 5`, and `0(0) = 1`

### Operations

| Operation | Symbol | Rule |
|-----------|--------|------|
| Addition | `+` | Expands the amount of objects under consideration. Same state: magnitudes combine. Mixed: unresolved |
| Subtraction | `-` | Contracts the amount of objects under consideration. (If the domain of consideration is constricted to nothing then the result is void. Void is not an object, nor the new zero, it simply means we are not considering anything on which to act.) Same state: magnitudes reduce. Mixed: unresolved|
| Multiplication | `*` | Magnitudes multiply. States combine (present*present=present, absent*present=absent, absent*absent=present) |
| Division | `/` | Magnitudes divide. States combine same as multiplication. Division by 0 is defined! |
| Erasure | `erased` | Same state required. Remainder keeps state, erased portion flips state |

### Result Types

- **AbsentNumber**: A number with a state (present or absent)
- **Void**: Complete cancellation — not zero, but the absence of any quantity under consideration
- **ErasureResult**: Two parts — remainder (keeps state) and erased portion (flipped state)
- **Unresolved**: An expression that cannot be simplified (e.g., adding present + absent)

## API Reference

### Types

- `AbsentNumber(value, absence_level=0)` — A number with a state. `absence_level` 0 = present, 1 = absent
- `Void` / `VOID` — Represents complete cancellation
- `ErasureResult(remainder, erased)` — Result of an erasure operation
- `Unresolved(left, op, right)` — An expression that can't be simplified

### Functions

- `add(x, y)` — Add two AbsentNumbers
- `subtract(x, y)` — Subtract two AbsentNumbers
- `multiply(x, y)` — Multiply two AbsentNumbers
- `divide(x, y)` — Divide two AbsentNumbers
- `erase(x, y)` — Erase y from x (both must have same state)
- `solve(expr_string)` — Parse and evaluate a string expression
- `format_result(result)` — Convert any result to a readable string
- `parse_number(s)` — Parse a string like `"5(0)"` into an AbsentNumber

### Constants

- `ALL_OPERATIONS` — Dictionary describing all operations with rules and examples

## License

MIT
