Metadata-Version: 2.4
Name: nultra
Version: 0.2.0
Summary: Nultra aperture math and rotating temporal gate primitives
Author: NultraChain contributors
License: MIT
Project-URL: Homepage, https://github.com/nultra/nultra
Project-URL: Issues, https://github.com/nultra/nultra/issues
Keywords: nultra,aperture,blockchain,consensus,simulation,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.23
Provides-Extra: demo
Requires-Dist: Flask>=3.0; extra == "demo"
Requires-Dist: Flask-SocketIO>=5.3; extra == "demo"
Requires-Dist: python-dotenv>=1.0; extra == "demo"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"

# nultra

`nultra` is a small Python library for building systems around the Nultra
aperture:

```text
A_gamma(t) = [0.5 * (1 + sin(omega * t + phi))] ** gamma

A_gamma,eta(t) = 0 if A_gamma(t) < eta
               = A_gamma(t) otherwise
```

The result is a deterministic temporal gate. When `A_gamma,eta(t) == 0.0`, the
system is in a hard null plateau. Applications can use that plateau as the only
valid moment for state transitions such as block proposals, checkpoints,
maintenance updates, or simulation events.

Version `0.2.0` adds rotating aperture parameters. The tuple
`(omega, phi, gamma, eta)` can rotate only during a valid null plateau, making
future safe windows a moving target while keeping honest participants in sync.

## Installation

```bash
pip install nultra
```

To run the optional NultraChain dashboard:

```bash
pip install "nultra[demo]"
```

## Quickstart

```python
from nultra import NultraOperator

op = NultraOperator(omega=0.5, gamma=2.0, eta=0.25)

t = 6.30
aperture = op.get_aperture(t)

if op.is_null_plateau(t):
    print("State transition allowed")
else:
    print("Gate is closed")
```

### Blending State

The canonical Nultra blend is:

```python
from nultra import NultraOperator

op = NultraOperator()

current_state = 10.0
candidate_state = 25.0

next_state = op.blend(current_state, candidate_state, t=1.5)
```

When the aperture is zero, the state is preserved. When it opens, the candidate
state contributes according to the aperture value.

## Rotating Aperture Parameters

Manual rotations are strictly gated:

```python
from nultra import NultraOperator, RotationGateError

op = NultraOperator(omega=0.5, phi=0.0, gamma=2.0, eta=0.25)

try:
    event = op.rotate(t=6.30, reason="checkpoint")
except RotationGateError as exc:
    print(exc)
else:
    print(event.old_params)
    print(event.new_params)
```

Automatic rotation is timer-driven, but still plateau-gated:

```python
from nultra import NultraOperator

op = NultraOperator(
    omega=0.5,
    gamma=2.0,
    eta=0.25,
    auto_rotate=True,
    rotation_interval_seconds=20,
)

for t in simulation_clock():
    event = op.maybe_auto_rotate(t)
    if event is not None:
        print("rotated", event.to_dict())
```

If the timer is due while the aperture is open, no rotation happens. The next
null plateau accepts the rotation message.

## Running the Demo

After installing the demo extra:

```bash
nultra demo
```

Then open:

```text
http://127.0.0.1:5000
```

The dashboard includes:

- live aperture graph
- honest nodes and a Mallory attacker simulation
- blockchain explorer
- admin panel for aperture parameters
- auto-rotation toggle
- rotation interval control
- manual plateau-gated rotation button
- rotation countdown and flash banner

From a source checkout, this also works:

```bash
python run.py
```

## Why This Is Useful

Nultra math is useful anywhere state transitions should be rare, timed,
auditable, or coordinated:

- permissioned blockchain consensus
- checkpoint admission windows
- anti-spam transaction gating
- secure maintenance windows for edge devices
- simulations where mutation should happen only at deterministic moments

The package does not claim to be a complete blockchain consensus protocol by
itself. It provides the reusable aperture primitive and rotation machinery that
larger blockchain, security, and simulation projects can build on.

## Development

Run the tests from the project root:

```bash
python -m unittest
```

Build a wheel:

```bash
python -m build
```
