nbody_sim_core 0.1.2

Engine-agnostic N-body simulation core models, contracts, adapters, and utilities.

nbody_sim_core

Engine-agnostic N-body simulation core package for Dart. High-iteration N-body vibes, production-ready core APIs.

nbody_sim_core provides:

1. Physics domain models and contracts.
2. Multiple engine backends (Dart, Isolate, Rust FFI).
3. Scenario and snapshot serialization utilities.
4. Schema migration and validation helpers.
5. Embedded Rust crate + native build scripts.

Install

dependencies:
  nbody_sim_core: ^0.1.2

Public API

import 'package:nbody_sim_core/nbody_sim_core.dart';

Barrel exports:

1. models.dart: configs, vectors, bodies, state, telemetry, edit contracts.
2. engine.dart: SimulationEngine + concrete backends.
3. scenario.dart: schema validator + migrator APIs.

Core Concepts

1. SimulationConfig
   • Integrator: semiImplicitEuler, velocityVerlet, rk4
   • Collision: elastic, inelasticMerge, ignore
   • dt policy: fixed, adaptive
   • Solver: pairwise, barnesHut, auto
2. SimulationBody
   • Required: id, mass, radius, position, velocity, colorValue
3. SimulationEngine contract
   • initialize, setConfig, applyEdit, step
   • loadScenario, saveScenario
   • snapshot, restoreSnapshot
   • getState, dispose

Quick Start (Pure Dart backend)

import 'package:nbody_sim_core/nbody_sim_core.dart';

Future<void> main() async {
  final engine = DartSimulationEngine();

  await engine.initialize(
    config: SimulationConfig.scientificDefault,
    bodies: const [
      SimulationBody(
        id: 'sun',
        mass: 1000,
        radius: 2.0,
        position: Vec2.zero,
        velocity: Vec2.zero,
        colorValue: 0xFFFFD54F,
      ),
      SimulationBody(
        id: 'planet',
        mass: 1,
        radius: 0.5,
        position: Vec2(12, 0),
        velocity: Vec2(0, 9.2),
        colorValue: 0xFF64B5F6,
      ),
    ],
  );

  final summary = await engine.step(240);
  final state = engine.getState();

  print('tick=${state.tick}, simTime=${state.simTime}, mode=${summary.lastSolverMode}');
  await engine.dispose();
}

Backend Options

Use whichever backend fits your runtime and performance goals.

1. DartSimulationEngine
   • Easiest setup.
   • No native prerequisites.
2. IsolateSimulationEngine
   • Runs simulation off the UI/main isolate.
   • Backend selection: EngineBackend.auto, EngineBackend.rust, EngineBackend.dart.
3. RustFfiSimulationEngine
   • Direct native Rust backend.
   • Highest performance path when native library is present.

Example:

import 'package:nbody_sim_core/engine.dart';
import 'package:nbody_sim_core/models.dart';

final engine = IsolateSimulationEngine(
  backend: EngineBackend.auto,
  // Optional:
  // rustLibraryPath: '/absolute/path/to/libgravity_engine.dylib',
);

Direct Rust backend:

import 'package:nbody_sim_core/engine.dart';

final engine = RustFfiSimulationEngine(
  // Optional if GRAVITY_ENGINE_LIB is set or library is in ./native:
  libraryPath: '/absolute/path/to/libgravity_engine.dylib',
);

Rust Native Build

The package includes:

1. Rust crate: rust/gravity_engine
2. Build scripts:
   • tool/build_rust_engine.sh
   • tool/build_rust_engine.ps1

From package root:

# Run Rust tests
cargo test --manifest-path rust/gravity_engine/Cargo.toml

# Build native library for host target and copy to ./native/<abi>/
./tool/build_rust_engine.sh

# Build specific targets and copy to ./native/<abi>/
./tool/build_rust_engine.sh aarch64-apple-darwin x86_64-apple-darwin

On Windows PowerShell:

.\tool\build_rust_engine.ps1

Generated library names:

1. macOS: libgravity_engine.dylib
2. Linux: libgravity_engine.so
3. Windows: gravity_engine.dll

Bundled ABI folders:

1. native/macos-arm64/
2. native/macos-x64/
3. native/linux-x64/
4. native/windows-x64/

Rust Library Discovery

When using Rust backends, RustFfiBindings resolves the native library in this order:

1. Explicit libraryPath passed into engine/bindings.
2. GRAVITY_ENGINE_LIB environment variable.
3. ./native/<abi>/<platform-library-name>
4. ./native/<platform-library-name>
5. ./rust/gravity_engine/target/release/<platform-library-name>
6. <nbody_sim_core package root>/native/<abi>/<platform-library-name>
7. <nbody_sim_core package root>/native/<platform-library-name>
8. Dynamic loader default lookup by filename.

The package root path is resolved from the consumer app's .dart_tool/package_config.json, so binaries bundled inside the package can be loaded without manually copying them into app cwd.

Prebuilt Binary Pipeline

Desktop Rust FFI targets are built in CI via:

1. .github/workflows/build-native-binaries.yml

Current CI matrix:

1. macOS: aarch64-apple-darwin, x86_64-apple-darwin
2. Linux: x86_64-unknown-linux-gnu
3. Windows: x86_64-pc-windows-msvc

Runtime Edits (Create/Update/Delete Bodies)

import 'package:nbody_sim_core/models.dart';

await engine.applyEdit(
  const BodyCreate(
    SimulationBody(
      id: 'probe',
      mass: 0.1,
      radius: 0.1,
      position: Vec2(0, 20),
      velocity: Vec2(6, 0),
      colorValue: 0xFFFFFFFF,
    ),
  ),
);

await engine.applyEdit(
  const BodyUpdate(
    id: 'probe',
    velocity: Vec2(6.5, 0.2),
    label: 'Science Probe',
    kind: 'probe',
  ),
);

await engine.applyEdit(const BodyDelete('probe'));

Scenario and Snapshot APIs

import 'package:nbody_sim_core/models.dart';

// Save current state as scenario
final scenario = await engine.saveScenario();

// Restore scenario
await engine.loadScenario(scenario);

// Point-in-time snapshot
final snap = await engine.snapshot();
await engine.restoreSnapshot(snap);

JSON import/export:

import 'dart:convert';
import 'package:nbody_sim_core/models.dart';

// Export scenario JSON string
final scenario = await engine.saveScenario();
final scenarioJsonString = jsonEncode(scenario.toJson());

// Import scenario JSON string
final parsedScenarioMap = jsonDecode(scenarioJsonString) as Map<String, dynamic>;
final importedScenario = ScenarioModel.fromJson(parsedScenarioMap);
await engine.loadScenario(importedScenario);

// Export snapshot JSON string
final snapshot = await engine.snapshot();
final snapshotJsonString = jsonEncode(snapshot.toJson());

// Import snapshot JSON string
final parsedSnapshotMap = jsonDecode(snapshotJsonString) as Map<String, dynamic>;
final importedSnapshot = SnapshotModel.fromJson(parsedSnapshotMap);
await engine.restoreSnapshot(importedSnapshot);

Schema Migration + Validation

import 'package:nbody_sim_core/scenario.dart';

final migrated = ScenarioSchemaMigrator.migrateToLatest(rawJson);
final issues = ScenarioSchemaValidator.validateScenarioJson(migrated);

if (issues.isNotEmpty) {
  for (final issue in issues) {
    print(issue); // "<path>: <message>"
  }
}

Deterministic vs Adaptive Notes

1. Deterministic mode is designed for replayable runs.
2. SimulationConfig.validate() rejects deterministic == true with DtPolicy.adaptive.
3. For exact replay workflows, keep:
   • deterministic: true
   • dtPolicy: DtPolicy.fixed

Minimal Lifecycle Pattern

final engine = IsolateSimulationEngine();
await engine.initialize(config: SimulationConfig.scientificDefault, bodies: initialBodies);
await engine.step(1);
final state = engine.getState();
await engine.dispose();

Troubleshooting

1. Error: unable to open gravity engine dynamic library
   • Build native library with ./tool/build_rust_engine.sh.
   • Set GRAVITY_ENGINE_LIB to an absolute library path.
   • Or pass rustLibraryPath explicitly.
2. StateError: Rust engine has not been initialized
   • Call initialize() before step, setConfig, applyEdit, etc.
3. Schema validation failures
   • Run migrator first: ScenarioSchemaMigrator.migrateToLatest(...).
   • Re-run validator and inspect issue paths/messages.

License

MIT (see LICENSE).