User Customization & API

Learn how to customize the iTensor platform for your specific research needs and integrate with the API.

Overview

iTensor provides extensive customization options and a powerful API that allows researchers and developers to tailor the platform to their specific needs. This flexibility enables users to define custom tensors, simulation parameters, and differential equation settings for their unique research requirements.

The customization capabilities of iTensor are designed with both usability and flexibility in mind, allowing researchers to focus on their scientific questions rather than implementation details.

Tensor Definition Customization

Users can input their own tensor definitions through both the web interface and API:

Custom Tensor Definition Options

Component-wise Definition: Define tensor components directly using mathematical expressions.
Symbolic Definition: Create tensors using symbolic variables and expressions.
Numerical Arrays: Input tensor data as numerical arrays for computational analysis.
Predefined Templates: Use and modify template tensors for common physical scenarios.
Coordinate System Specification: Define tensors in specific coordinate systems (e.g., Cartesian, spherical, custom curvilinear).

Web Interface

The web interface provides intuitive forms for defining custom tensors:

1. Navigate to the "Define Tensor" page
2. Select tensor type (scalar, vector, rank-2 tensor, etc.)
3. Choose coordinate system 
4. Define components using the interactive editor
5. Validate and save your tensor definition
6. Use in simulations or calculations

Code Example

Here's an example of defining a custom metric tensor for a Schwarzschild black hole:

// Example: Define Schwarzschild metric tensor using the JavaScript client library
const schwarzschildMetric = new iTensor.SymbolicTensor({
  rank: 2,
  symmetry: 'symmetric',
  components: [
    [(1 - 2*M/r), 0, 0, 0],
    [0, -1/(1 - 2*M/r), 0, 0],
    [0, 0, -r**2, 0],
    [0, 0, 0, -r**2 * Math.sin(theta)**2]
  ],
  variables: {
    M: symbolM, // black hole mass
    r: symbolR, // radial coordinate
    theta: symbolTheta // angular coordinate
  },
  coordinateSystem: 'spherical'
});

Simulation Parameters

Users can customize simulation parameters to model specific black hole scenarios:

Black Hole Parameters

Mass: Set the black hole mass (in solar masses or geometric units)
Spin: Configure rotation parameter (0 for Schwarzschild, 0-1 for Kerr)
Charge: Add electric charge for Reissner-Nordström or Kerr-Newman models
Cosmological Constant: Include for de Sitter or anti-de Sitter spacetimes

Environment Settings

Accretion Disk: Configure density profile, temperature distribution, and opacity
Background: Set starfield, nearby objects, or custom background images
Observer Position: Define viewing location and orientation
Time Evolution: Set simulation duration and time step parameters

API Parameter Example

// Example: Configure simulation parameters via API
const simulationConfig = {
  blackHole: {
    type: "kerr",
    mass: 5.0,  // 5 solar masses
    spin: 0.9,  // 90% of maximum rotation
    charge: 0   // No charge
  },
  accretionDisk: {
    model: "novikov-thorne",
    innerRadius: 3.0,  // In gravitational radii
    outerRadius: 35.0,
    density: {
      profile: "power-law",
      parameters: {
        index: -0.5
      }
    }
  },
  observer: {
    distance: 1000,  // In gravitational radii
    inclination: 75, // In degrees from polar axis
    azimuth: 0       // In degrees
  },
  simulation: {
    duration: 1000,   // In M units
    timeStep: 0.1,
    integrator: "rk4" // Runge-Kutta 4th order
  }
};

// Send configuration to API
const response = await fetch('https://api.itensor.org/blackhole/simulation', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(simulationConfig)
});

const simulation = await response.json();

Differential Equation Settings

iTensor provides tools for setting up and solving differential equations in curved spacetime:

Differential Equation Customization

Equation Type: Define ordinary or partial differential equations using tensor operations.
Integration Method: Select from various numerical integration techniques (Runge-Kutta, adaptive step-size, etc.).
Step Size Control: Configure adaptive step size parameters for optimal accuracy vs. performance.
Boundary Conditions: Set initial or boundary conditions for differential equations.
Tolerance Settings: Specify error tolerances and convergence criteria.

These settings allow researchers to precisely control the behavior of simulations and ensure appropriate numerical treatment of their specific physical problems.

API Endpoints

iTensor provides a comprehensive REST API for programmatic access to all platform capabilities:

Endpoint	Method	Description
/api/tensors/symbolic	POST	Perform symbolic tensor operations
/api/tensors/numerical	POST	Execute numerical tensor calculations
/api/blackhole/parameters	GET, POST	Retrieve or set black hole parameters
/api/blackhole/simulation	POST	Run black hole simulations
/api/differential/solve	POST	Solve differential equations in curved spacetime
/api/visualization/render	POST	Generate visualizations from calculation results
/api/coordinates/transform	POST	Transform between different coordinate systems

Each API endpoint accepts JSON-formatted input parameters and returns results in a structured JSON format. Complete API documentation, including parameter formats, response structures, and example requests, is available in the API Reference section.

API Authentication

All API requests require authentication using either API keys or OAuth 2.0 tokens. Authentication details can be found in the API Authentication Guide.

Integration with External Tools

iTensor is designed to integrate with external analysis tools and scientific workflows:

Data Export Formats

CSV/TSV: For spreadsheet analysis
HDF5: For scientific datasets
JSON/YAML: For web applications
VTK: For visualization in ParaView
NumPy Arrays: For Python analysis

Integration Options

Client Libraries: For Python, JavaScript, and MATLAB
Jupyter Notebooks: Direct integration
Webhooks: For event-driven workflows
REST API: For custom integrations
Data Pipelines: For automated processing

Python Client Example

# Example: Using the Python client library to integrate with external tools
import itensor
import numpy as np
import matplotlib.pyplot as plt
from scipy.integrate import solve_ivp

# Initialize client
client = itensor.Client(api_key="your_api_key")

# Define a Kerr black hole
black_hole = client.BlackHole(mass=1.0, spin=0.9)

# Get geodesic equations in tensor form
geodesic_eqs = black_hole.get_geodesic_equations()

# Convert to numerical function for scipy
def geodesic_rhs(t, y):
    position = y[0:4]  # t, r, theta, phi
    velocity = y[4:8]  # dt/ds, dr/ds, dtheta/ds, dphi/ds
    
    # Use iTensor API to compute accelerations
    acceleration = client.tensors.numerical.evaluate(
        tensor=geodesic_eqs,
        values={
            'x': position,
            'v': velocity
        }
    )
    
    return np.concatenate([velocity, acceleration])

# Solve using scipy
initial_state = [0, 20, np.pi/2, 0, 1, 0, 0, 0.1]  # Initial conditions
solution = solve_ivp(
    geodesic_rhs,
    t_span=[0, 1000],
    y0=initial_state,
    method='RK45',
    rtol=1e-8
)

# Plot results using matplotlib
plt.figure(figsize=(10, 8))
plt.plot(solution.y[1], solution.y[3])
plt.title("Particle Trajectory in Kerr Spacetime")
plt.xlabel("r (Gravitational Radii)")
plt.ylabel("φ (Radians)")
plt.grid(True)
plt.show()

# Store results back in iTensor for visualization
trajectory_id = client.visualizations.store_trajectory(
    coordinates=solution.y.T,
    metadata={
        "black_hole": "kerr",
        "mass": 1.0,
        "spin": 0.9
    }
)

print(f"View your trajectory visualization at: https://itensor.org/visualize/{trajectory_id}")

Configuration Options

The platform provides extensive configuration options to tailor simulations to specific research needs:

Key Configuration Options

Integration Methods: Choose from Runge-Kutta (RK4, RK45), symplectic, or specialized relativistic integrators for different accuracy vs. performance needs.
Step Sizes: Configure fixed or adaptive time steps for simulations, with options for error control and handling of stiff equations.
Coordinate System Selection: Select from predefined coordinate systems (Cartesian, spherical, Boyer-Lindquist, Kerr-Schild, etc.) or define custom curvilinear coordinates.
Physical Constants: Set units (SI, geometric, natural) and physical constants for simulations.
Computation Settings: Configure precision, parallelization, and hardware acceleration options.
Visualization Options: Set rendering quality, animation parameters, and output formats.

These configuration options can be set through the web interface or programmatically via the API. Configurations can be saved as profiles and reused or shared with collaborators.