Graviton Python SDK

The Graviton SDK provides a seamless way to connect your local mathematical models (built with SymPy) to the Graviton Supercompute platform.

Installation

pip install graviton-sdk

Quick Start (Jupyter/Colab)

The SDK is designed to work beautifully in interactive environments.

import sympy as sp
import graviton as gv

# 1. Authenticate (Use the public evaluation key for prototyping)
gv.login('a-little-more-art-than-science')

# 2. Define a complex model
x, y = sp.symbols('x y')
f = sp.sin(x)**2 + sp.exp(-y) * sp.cos(x)

# 3. Display with the Graviton "Compute" button
gv.expr(f)

Programmatic Workflow

For advanced integrations, you can use the flattened API to evaluate and compute programmatically.

# 1. Evaluate to get JSON data
eval_data = gv.evaluate(f, options={"type": "JSON"})

# 2. Use flattened access for cost and ID
cost = eval_data['cost']
job_id = eval_data['id']

print(f"Estimated Cost: {cost:.2f} credits")

# 3. Compute using the ID directly
job = gv.compute(job_id, options={"auto_charge": True})
result = job.wait()
print(f"Result: {result}")

Astrophysics & N-Body Simulations (REBOUND & Mercury)

Graviton provides specialized Turing nodes for high-density N-body Hamiltonian simulations.

REBOUND Example

sim_payload = {
    "t": "rebound",
    "sim_time": 36500.0,
    "time_step": 0.1,
    "bodies": [
        {"name": "Sun", "mass": 1.0, "x": 0.0, "y": 0.0, "z": 0.0},
        {"name": "Earth", "mass": 3.0e-6, "a": 1.0, "e": 0.0167}
    ]
}

eval_data = gv.evaluate(sim_payload)
print(f"Estimated Cost: {eval_data.cost} credits")

job = gv.compute(eval_data.id)
results = job.wait()
print(results)

Mercury ETL Parser

If you have legacy Mercury parameter datasets (param.in, big.in, small.in), you can load them directly using gv.load_mercury:

# Automatically parses Mercury parameter files into a Graviton payload
mercury_payload = gv.load_mercury("./my_mercury_simulation/")

eval_data = gv.evaluate(mercury_payload)
job = gv.compute(eval_data.id)
results = job.wait()

How it Works

When you call gv(formula), the SDK:

1. Serializes the SymPy object into a structured srepr format.
2. Generates a rich HTML representation with a LaTeX preview.
3. Adds a secure button that opens the Graviton Dashboard with your formula pre-loaded.

This allows you to leverage Graviton's massive cloud compute resources for complexity analysis and evaluation without ever leaving your research environment.

Security

Graviton follows a "Data, not Code" security model. The SDK only transmits the mathematical structure of your model, not arbitrary Python code. Your local environment remains isolated, and all authentication is handled securely via the Graviton web platform.