Skip to content

pycauset.CausalSet

class CausalSet(n=None, density=None, spacetime=None, seed=None)

The CausalSet class represents a causal set generated by sprinkling points into a spacetime manifold. It uses a memory-efficient "stateless" sprinkling algorithm that allows for the generation of extremely large causal sets (billions of elements) without storing the coordinates of the points in RAM.

Parameters

  • n (int, optional): The number of elements (points) to sprinkle.
  • density (float, optional): The density of the sprinkling. If provided, \(N\) is calculated as a Poisson random variable with mean \(\text{density} \times \text{volume}\). You must provide either n or density.
  • spacetime (CausalSpacetime, optional): The spacetime manifold to sprinkle into. If None, defaults to a 2-dimensional Minkowski Diamond.
  • seed (int, optional): The random seed for the sprinkling process. If None, a random seed is generated.

Properties

causal_matrix

@property
def causal_matrix(self) -> TriangularBitMatrix

(Alias: C)

Returns the causal matrix of the set. This is the primary "product" of the CausalSet instance. It is a TriangularBitMatrix where M[i, j] = 1 if element i causally precedes element j (\(i \prec j\)), and 0 otherwise.

Storage Note: The CausalSet instance itself is very lightweight. It stores only the metadata (\(N\), seed, spacetime definition) and a handle to this matrix. The matrix itself is backed by a file on disk (memory-mapped), so creating a CausalSet does not load the entire structure into RAM. The coordinates of the sprinkled points are not stored; they are generated transiently to compute this matrix and then discarded.

n

@property
def n(self) -> int

(Alias: N)

The number of elements in the causal set.

density

@property
def density(self) -> float

(Alias: rho)

The density of the sprinkling, calculated as \(N / V\), where \(V\) is the volume of the spacetime region.

spacetime

@property
def spacetime(self) -> CausalSpacetime

The spacetime manifold object used for sprinkling.

Methods

__init__

def __init__(self, n: int = None, density: float = None, spacetime=None, seed: int = None, matrix=None)

Initializes the causal set.

  • Sprinkling Mode: Provide n (or density), and optionally spacetime and seed. The set will be generated by sprinkling points.
  • Loading Mode: Used internally by load(). Provide n, spacetime, seed, and matrix.

compute_k

def compute_k(self, a: float = 1.0) -> TriangularFloatMatrix

Compute the K-matrix (retarded propagator) for this causal set.

  • a (float): The non-locality scale parameter. Defaults to 1.0.
  • Returns: A TriangularFloatMatrix representing \(K = C(aI + C)^{-1}\).

save

def save(self, path: str)

Save the CausalSet to a single-file .pycauset container.

  • path (str): The destination path.

load

@staticmethod
def load(path: str) -> CausalSet

Load a CausalSet from a .pycauset container. This reconstructs the CausalSet object with the exact same parameters and matrix as the saved instance, without re-running the sprinkling process.

  • path (str): Path to the .pycauset file.
  • Returns: A new CausalSet instance.

__len__

def __len__(self) -> int

Returns the number of elements (\(N\)).

Examples

import pycauset

# 1. Create and Save
c = pycauset.CausalSet(1000, seed=42)
c.save("my_universe")

# 2. Load
c_loaded = pycauset.CausalSet.load("my_universe.pycauset")
print(f"Loaded N={len(c_loaded)}")

# 3. Compute K
K = c.compute_k(a=1.5)

Examples

import pycauset

# Create a causal set with 1000 elements in 2D Minkowski space
c = pycauset.CausalSet(1000)

# Access the causal matrix (using the alias C)
M = c.C

# Check if element 0 precedes element 10
is_causal = M[0, 10]

# Create a causal set with a specific seed for reproducibility
c_repro = pycauset.causet(n=500, seed=42)
print(c_repro.causal_matrix)