Metadata-Version: 2.2
Name: pycauset
Version: 0.1.0
Summary: High-performance Causal Set matrix operations using memory-mapped files
Author-Email: BrorH <your.email@example.com>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C++
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Project-URL: Homepage, https://github.com/BrorH/pycauset
Project-URL: Repository, https://github.com/BrorH/pycauset
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# PyCauset

**PyCauset** is a high-performance Python module designed for numerical work with [Causal Sets](https://en.wikipedia.org/wiki/Causal_sets). It is built to handle massive matrices (up to $N=10^6$) that exceed available RAM by leveraging memory-mapped files and efficient C++ backends.

## Why PyCauset?

For a causal set of size $N$, the relevant mathematical objects are typically of order $\mathcal O(N^2)$ and operations are $\mathcal O(N^3)$. For even moderate sizes like $N=10,000$, standard in-memory libraries like NumPy can struggle with memory limits.

**PyCauset solves this by:**
*   **Memory Mapping**: Storing matrices on disk and loading only necessary chunks into RAM.
*   **Bit Packing**: Storing boolean matrices (causal relations) as individual bits, reducing storage requirements by 8x-64x compared to standard types.
*   **C++ Efficiency**: Core operations are implemented in optimized C++.

## Installation

### Prerequisites
PyCauset requires a C++ compiler to build the native extension.
*   **Windows**: Install **Visual Studio Build Tools** with the "Desktop development with C++" workload.
*   **Linux/macOS**: Install `gcc` or `clang`.

### Build & Install
Clone the repository and run the build script:

```powershell
# Build the C++ extension and Python module
./build.ps1 -Python

# To run tests as well
./build.ps1 -All
```

## Quick Start

### 1. Creating Matrices
The primary structure for causal sets is the `TriangularBitMatrix` (aliased as `CausalMatrix`).

```python
import pycauset

# Create a random 1000x1000 causal matrix (Bernoulli p=0.5)
C = pycauset.CausalMatrix.random(1000, density=0.5)

# Create an empty matrix (initialized to zeros)
C_empty = pycauset.CausalMatrix(1000)

# Create from a NumPy array
import numpy as np
arr = np.triu(np.random.randint(0, 2, (10, 10)), k=1).astype(bool)
C_from_np = pycauset.CausalMatrix(arr)
```

### 2. Matrix Operations
PyCauset supports standard arithmetic and specialized causal set operations.

```python
# Matrix Multiplication (Counting paths of length 2)
# Returns an IntegerMatrix
M = pycauset.matmul(C, C)

# Elementwise Multiplication
E = C * C

# Bitwise Inversion (NOT)
C_inv = ~C

# Linear Algebra Inversion (for dense float matrices)
# Returns a FloatMatrix
F = pycauset.FloatMatrix(100)
F_inv = pycauset.invert(F)
```

### 3. Computing the K-Matrix
A common operation in causal set theory is computing $K = C(aI + C)^{-1}$.

```python
# Compute K with scalar a=1.0
# Returns a TriangularFloatMatrix
K = pycauset.compute_k(C, a=1.0)
```

## Matrix Types

PyCauset uses a template-based architecture to support efficient storage for different data types:

| Class | Description | Storage |
|-------|-------------|---------|
| `TriangularBitMatrix` | Strictly upper-triangular boolean matrix. | 1 bit / element |
| `IntegerMatrix` | Dense matrix of 32-bit integers. | 4 bytes / element |
| `FloatMatrix` | Dense matrix of 64-bit floats. | 8 bytes / element |
| `TriangularFloatMatrix` | Strictly upper-triangular float matrix. | 8 bytes / element |

## Storage Management

PyCauset manages disk storage automatically to keep your workspace clean.

*   **Temporary Files**: All matrices are created as temporary files in a `.pycauset/` directory. These files are **automatically deleted** when your Python script exits (even if it crashes or is interrupted).
*   **Permanent Storage**: To keep a matrix, you **must** use the `save()` function.

```python
# This matrix is temporary and will be deleted at exit
temp = pycauset.CausalMatrix(500)

# Save it permanently to a specific path
pycauset.save(temp, "my_causet.pycauset")
```
