README
# particle-spatial
Spatial hash grid N-body simulation — a pure-computation Native Gene for the Rotifer Protocol.
## Algorithm
Partitions space into a uniform grid of fixed-size cells. For each particle, only computes gravitational forces from particles in the same cell and 8 neighboring cells (3×3 neighborhood). Long-range forces beyond the cell neighborhood are ignored.
Cell size is adaptive: `cellSize = max(2ε, 2 × √(area / n))`, scaling with the average inter-particle spacing and bounded by the softening parameter.
Integration uses the symplectic leapfrog (kick-drift-kick) scheme.
This approach trades long-range gravitational accuracy for raw speed — achieving near-O(n) performance when particles are roughly uniformly distributed. It's better suited for short-range-dominated systems (collisions, dense clusters) than for orbital mechanics where long-range gravity dominates.
## Usage
```bash
# Cluster preset (good fit for spatial hashing)
rotifer run particle-spatial --input '{"preset": "cluster", "count": 256}'
# Collision (where short-range forces dominate)
rotifer run particle-spatial --input '{"preset": "collision", "count": 512, "steps": 300}'
# Solar system (less accurate due to missing long-range forces)
rotifer run particle-spatial --input '{"preset": "solar"}'
```
## Presets
| Preset | Description |
|--------|-------------|
| `solar` | Central massive body + orbiting lighter bodies with circular velocities |
| `binary` | Two equal-mass stars in mutual orbit + debris ring |
| `cluster` | Random particles in a disk with small random velocities |
| `collision` | Two groups of particles approaching head-on |
## Output
- `particles` — final positions and velocities of all particles
- `steps_computed` — number of simulation steps executed
- `total_energy` — total system energy (kinetic + potential) for conservation validation
- `interactions_computed` — total neighbor-cell force evaluations
## Fitness Characteristics
| Metric | Expected |
|--------|----------|
| Success Rate | 1.0 (deterministic, no failure mode) |
| Accuracy | Low-medium (only short-range interactions, misses distant forces) |
| Complexity | ~O(n × steps) for uniform distributions |
| Interactions | Depends on particle clustering — much fewer than n² |
| Best For | Large N with short-range dominated interactions (collisions, dense clusters) |
| Weakness | Poor for orbital/long-range gravity (solar, binary) |
Spatial hash grid N-body simulation — a pure-computation Native Gene for the Rotifer Protocol.
## Algorithm
Partitions space into a uniform grid of fixed-size cells. For each particle, only computes gravitational forces from particles in the same cell and 8 neighboring cells (3×3 neighborhood). Long-range forces beyond the cell neighborhood are ignored.
Cell size is adaptive: `cellSize = max(2ε, 2 × √(area / n))`, scaling with the average inter-particle spacing and bounded by the softening parameter.
Integration uses the symplectic leapfrog (kick-drift-kick) scheme.
This approach trades long-range gravitational accuracy for raw speed — achieving near-O(n) performance when particles are roughly uniformly distributed. It's better suited for short-range-dominated systems (collisions, dense clusters) than for orbital mechanics where long-range gravity dominates.
## Usage
```bash
# Cluster preset (good fit for spatial hashing)
rotifer run particle-spatial --input '{"preset": "cluster", "count": 256}'
# Collision (where short-range forces dominate)
rotifer run particle-spatial --input '{"preset": "collision", "count": 512, "steps": 300}'
# Solar system (less accurate due to missing long-range forces)
rotifer run particle-spatial --input '{"preset": "solar"}'
```
## Presets
| Preset | Description |
|--------|-------------|
| `solar` | Central massive body + orbiting lighter bodies with circular velocities |
| `binary` | Two equal-mass stars in mutual orbit + debris ring |
| `cluster` | Random particles in a disk with small random velocities |
| `collision` | Two groups of particles approaching head-on |
## Output
- `particles` — final positions and velocities of all particles
- `steps_computed` — number of simulation steps executed
- `total_energy` — total system energy (kinetic + potential) for conservation validation
- `interactions_computed` — total neighbor-cell force evaluations
## Fitness Characteristics
| Metric | Expected |
|--------|----------|
| Success Rate | 1.0 (deterministic, no failure mode) |
| Accuracy | Low-medium (only short-range interactions, misses distant forces) |
| Complexity | ~O(n × steps) for uniform distributions |
| Interactions | Depends on particle clustering — much fewer than n² |
| Best For | Large N with short-range dominated interactions (collisions, dense clusters) |
| Weakness | Poor for orbital/long-range gravity (solar, binary) |
Phenotype
Input
| Property | Type | Description |
|---|---|---|
| G | number = 1 | Gravitational constant |
| dt | number = 0.01 | Time step size |
| seed | number | Random seed for preset generation (deterministic output) |
| count | number = 64 | Number of particles for preset generation |
| steps | number = 100 | Number of simulation steps |
| preset | solar | binary | cluster | collision | Preset particle configuration |
| particles | array | Initial particle states. Ignored if preset is provided. |
| softening | number = 0.01 | Softening parameter to prevent singularity at close range |
Output
| Property | Type | Req | Description |
|---|---|---|---|
| particles | array | ✓ | Final particle states after simulation |
| total_energy | number | ✓ | Total system energy (kinetic + potential) at final state |
| steps_computed | number | ✓ | Actual number of simulation steps computed |
| interactions_computed | number | ✓ | Total pairwise force evaluations across all steps |
Raw JSON Schema
inputSchema
{
"type": "object",
"required": [],
"properties": {
"G": {
"type": "number",
"default": 1,
"description": "Gravitational constant"
},
"dt": {
"type": "number",
"default": 0.01,
"description": "Time step size"
},
"seed": {
"type": "number",
"description": "Random seed for preset generation (deterministic output)"
},
"count": {
"type": "number",
"default": 64,
"maximum": 2048,
"minimum": 2,
"description": "Number of particles for preset generation"
},
"steps": {
"type": "number",
"default": 100,
"maximum": 10000,
"minimum": 1,
"description": "Number of simulation steps"
},
"preset": {
"enum": [
"solar",
"binary",
"cluster",
"collision"
],
"type": "string",
"description": "Preset particle configuration"
},
"particles": {
"type": "array",
"items": {
"type": "object",
"required": [
"x",
"y",
"vx",
"vy",
"mass"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"vx": {
"type": "number"
},
"vy": {
"type": "number"
},
"mass": {
"type": "number"
}
}
},
"description": "Initial particle states. Ignored if preset is provided."
},
"softening": {
"type": "number",
"default": 0.01,
"description": "Softening parameter to prevent singularity at close range"
}
}
}outputSchema
{
"type": "object",
"required": [
"particles",
"steps_computed",
"total_energy",
"interactions_computed"
],
"properties": {
"particles": {
"type": "array",
"items": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"vx": {
"type": "number"
},
"vy": {
"type": "number"
},
"mass": {
"type": "number"
}
}
},
"description": "Final particle states after simulation"
},
"total_energy": {
"type": "number",
"description": "Total system energy (kinetic + potential) at final state"
},
"steps_computed": {
"type": "number",
"description": "Actual number of simulation steps computed"
},
"interactions_computed": {
"type": "number",
"description": "Total pairwise force evaluations across all steps"
}
}
}Arena History
| Date | Fitness | Safety | Calls |
|---|---|---|---|
| Mar 17 | 1.0000 | 1.00 | 1 |