spacelearn 0.1.0__tar.gz

spacelearn-0.1.0/.github/workflows/spacelearn.yml

@@ -0,0 +1,24 @@
+name: spacelearn
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install tox
+      run: |
+        python -m pip install --upgrade pip
+        pip install tox
+
+    - name: Run tests with tox
+      run: tox

spacelearn-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+venv/
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.tox/

spacelearn-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2026] [Tobias Karusseit]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spacelearn-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: spacelearn
+Version: 0.1.0
+Summary: Guided latent subspace learning for deep neural networks
+Project-URL: Homepage, https://github.com/K-T0BIAS/SPACE
+Project-URL: Issues, https://github.com/K-T0BIAS/SPACE/issues
+Author-email: Tobias Karusseit <karusseittobi@gmail.com>
+License: MIT License
+        
+        Copyright (c) [2026] [Tobias Karusseit]
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: latent-space,physics-informed,pytorch,representation-learning,subspaces
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: torch>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: tox; extra == 'dev'
+Description-Content-Type: text/markdown
+
+[README](./README.md)
+
+# SPACE (Subspace Partitioning for Accessible Controlled Encodings)
+
+`SPACE-Learn` provides a utility library build on `pytorch`, that offers functions to train your Deep-Learning Models on the `Latent-SPACE` regime. The SPACE method helps create structured and easy to decode embedding spaces or explicitly guide a models internal latent space using training side information. This method encodes features that are known during training time or intermediate results directly into a models latentspace. 
+
+## Example Setup
+
+### 1. Install
+
+```bash
+pip install spacelearn
+```
+
+### 2. Example Training Setup
+
+```python
+import torch
+from torch.optim import Adam
+from collections import defaultdict
+
+from spacelearn import (
+    solve_dims,
+    solve_subspaces,
+    combined_loss,
+)
+from spacelearn.data import input_to_quantity
+from spacelearn.optim import minimal_latent_dim
+
+from my_model import Model
+from my_data import (
+    DataLoader,
+    quantity_helper_a,
+    quantity_helper_b,
+)
+
+EPOCHS = 5
+LR = 1e-3
+
+MAX_BINS = 10
+
+# target variance retained by pooling
+BIN_THRESHOLDS = 0.80
+
+# target variance retained by subspaces
+K_THRESHOLDS = {
+    "A": 0.90,
+    "B": 0.85,
+}
+
+REEVAL_EVERY = 2
+INIT_SAMPLES = 100
+
+dataloader = DataLoader()
+
+# ------------------------------------------------------------------
+# 1. Collect data for dimension estimation
+# ------------------------------------------------------------------
+
+test_data = defaultdict(list)
+samples = []
+
+for i in range(INIT_SAMPLES):
+    sample = dataloader[i]
+
+    test_data["A"].append(
+        quantity_helper_a(samples=sample)
+    )
+    test_data["B"].append(
+        quantity_helper_b(samples=sample)
+    )
+
+    samples.append(sample)
+
+test_data["A"] = torch.stack(test_data["A"])
+test_data["B"] = torch.stack(test_data["B"])
+
+samples = torch.stack(samples)
+
+# ------------------------------------------------------------------
+# 2. Estimate n and k
+# ------------------------------------------------------------------
+
+dims = solve_dims(
+    test_data,
+    max_bins=MAX_BINS,
+    bin_thresholds=BIN_THRESHOLDS,
+    k_thresholds=K_THRESHOLDS,
+    k_per_quantity=True,
+)
+
+# shared pooling resolution
+N = next(iter(dims.values()))[0]
+
+# per-quantity subspace dimensions
+K = {q: k for q, (_, k) in dims.items()}
+
+# latent dimension
+D = minimal_latent_dim(
+    K,
+    free_frac=0.10,
+)
+
+# ------------------------------------------------------------------
+# 3. Build quantity extraction helper
+# ------------------------------------------------------------------
+
+pool_helper = input_to_quantity(
+    N,
+    "avg",
+    A=quantity_helper_a,
+    B=quantity_helper_b,
+)
+
+# ------------------------------------------------------------------
+# 4. Initialize model
+# ------------------------------------------------------------------
+
+model = Model(D)
+optimizer = Adam(model.parameters(), lr=LR)
+
+# ------------------------------------------------------------------
+# 5. Training loop
+# ------------------------------------------------------------------
+
+W_prev = None
+
+for epoch in range(EPOCHS):
+
+    # periodically recompute subspaces
+    if epoch % REEVAL_EVERY == 0:
+
+        with torch.no_grad():
+            Z_ref = model(samples)
+
+        Y_ref = pool_helper(samples=samples)
+
+        WAV = solve_subspaces(
+            Z_ref,
+            Y_ref,
+            k=k,
+        )
+
+        W = WAV.W
+        A = WAV.A
+
+        if W_prev is None:
+            W_prev = {
+                q: w.clone()
+                for q, w in W.items()
+            }
+
+    for batch in dataloader:
+
+        Y = pool_helper(samples=batch)
+        Z = model(batch)
+
+        space_loss = combined_loss(
+            Z,
+            W,
+            A,
+            Y,
+            W_prev,
+        )
+
+        # task_loss = ...
+        # loss = task_loss + space_loss
+
+        optimizer.zero_grad()
+        space_loss.backward()
+        optimizer.step()
+
+    W_prev = {
+        q: w.clone()
+        for q, w in W.items()
+    }
+```
+
+
+## DOCS:
+
+[spacelearn](./docs/SPACELEARN.md)
+
+[spacelearn.settings](./docs/SETTINGS.md)
+
+[spacelearn.data](./docs/data/DATA.md)
+
+[spacelearn.loss](./docs/loss/LOSS.md)
+
+[spacelearn.optim](./docs/optim/OPTIM.md)

spacelearn-0.1.0/README.md

@@ -0,0 +1,169 @@
+# SPACE (Subspace Partitioning for Accessible Controlled Encodings)
+
+`spacelearn` is a utility library built on top of `PyTorch` that provides tools for training deep-learning models in the **Latent-SPACE** regime. The SPACE method helps create structured, interpretable, and easily decodable embedding spaces by explicitly guiding a model's internal latent representation using side information available during training.
+
+Rather than treating the latent space as an unconstrained representation, SPACE partitions it into dedicated subspaces that encode specific physical quantities, intermediate computations, or other known properties of the data. This allows these quantities to be decoded directly from the latent representation while still preserving unconstrained latent capacity for the model to learn additional features.
+
+#### [Documentation](./SPACE.md)
+
+## The Method
+
+### 1. Embedding Quantities
+
+Since SPACE is used to embed specific information into the latent space, the first step is defining the target quantities. These quantities may have any number of dimensions; however, the method generally works best when targets contain between roughly 10 and a few thousand elements.
+
+*Soft guidelines for target quantities:*
+
+* Quantities should contain enough information that they cannot easily be represented by only a few latent dimensions.
+
+  * **Bad example:** a 2D rotation matrix
+
+\[
+\mathcal{R}(\theta)=
+\left(
+\begin{matrix}
+\cos(\theta) & -\sin(\theta) \\
+\sin(\theta) & \cos(\theta)
+\end{matrix}
+\right)
+\]
+
+* **Good example:** the spatial gradient of a 64 × 64 image
+
+\[
+G_x=
+\left(
+\begin{matrix}
+-1 & 0 & 1 \\
+-2 & 0 & 2 \\
+-1 & 0 & 1
+\end{matrix}
+\right),
+\qquad
+G_y=
+\left(
+\begin{matrix}
+-1 & -2 & -1 \\
+0 & 0 & 0 \\
+1 & 2 & 1
+\end{matrix}
+\right)
+\]
+
+\[
+G_{A,x}=G_x*A,
+\qquad
+G_{A,y}=G_y*A
+\]
+
+* Quantities with only a few elements can often be encoded directly into a small number of latent dimensions instead of first projecting them into learned subspaces.
+* Quantities should exhibit predictable variance across samples or be analyzed using relatively high variance-retention thresholds. For quantities with highly variable sample-to-sample structure, it is often beneficial to estimate subspaces and decoders using large and diverse datasets.
+* Since SPACE relies heavily on singular value decompositions and eigendecompositions, the underlying data distributions should be reasonably well-conditioned.
+
+### 2. Setup / Hyperparameter Tuning
+
+Once the target quantities have been defined, SPACE provides utilities to estimate all major SPACE-specific hyperparameters:
+
+* `optimal_bins()` / `solve_dims()` for determining the pooling resolution `n`
+* `k_per_q()` / `solve_dims()` for determining subspace dimensions `k`
+* `minimal_latent_dim()` for determining the latent dimension `D`
+
+#### Step 1: Choose Pooling Resolution
+
+Use `optimal_bins()` (or `solve_dims()`) to estimate the minimum pooling resolution required to retain a desired fraction of spatial variance.
+
+You must choose a target variance-retention threshold for the pooled quantities. Depending on the structure of the quantity, this threshold may have a dramatic or only minor effect on the resulting pooling resolution.
+
+#### Step 2: Choose Subspace Dimensions
+
+After determining the pooling resolution, use `k_per_q()` (or `solve_dims()`) to estimate the minimum subspace dimension required for each quantity.
+
+The resulting value of `k` depends on:
+
+* The variance-retention threshold chosen for the subspace
+* The pooling resolution `n`
+* The structure and complexity of the quantity itself
+
+![image showing the relationship of n and k on 2D thermodynamic quantities](./docs/graphics/Threshold_analysis_2.png)
+
+*Relationship between pooling resolution (`n`) and subspace dimensionality (`k`) for 2D thermodynamic quantities (original quantity shape: 64 × 64).*
+
+#### Step 3: Choose the Latent Dimension
+
+Once `n` and `k` are known, use `minimal_latent_dim()` to estimate the required latent dimension `D`.
+
+This computation reserves enough latent capacity for all learned subspaces while optionally leaving a configurable fraction of the latent space unconstrained.
+
+We recommend reserving free latent capacity because:
+
+* Some quantities require additional latent freedom to find stable subspace geometries
+* Joint training setups often benefit from latent dimensions that are not explicitly assigned to any known quantity
+* Models frequently learn useful hidden representations that are not captured by the selected physical targets
+
+### 3. Training
+
+#### Step 1: Initialize Subspaces and Decoders
+
+Before beginning the main training loop, initialize the subspaces and decoders.
+
+We recommend collecting a dataset similar in size to the one used when estimating `n` and `k`.
+
+Subspaces and decoders can then be initialized using:
+
+```python
+WVA = solve_subspaces(Z, pooled_targets, k=k)
+```
+
+or individually through:
+
+* `principal_directions()`
+* `subspaces()`
+* `fit_decoders()`
+
+#### Step 2: Train Using the SPACE Objective
+
+Add the SPACE objective to your training loss in the same way as any other regularization term.
+
+The simplest approach is to use:
+
+```python
+loss = combined_loss(
+    Z,
+    W,
+    A,
+    pooled_targets,
+    W_prev
+)
+```
+
+Internally this combines:
+
+* `alignment_loss()`
+* `disentanglement_loss()`
+* `isotropy_loss()`
+* `stability_loss()`
+
+#### Step 3: Periodically Recompute Subspaces
+
+We recommend periodically recomputing:
+
+* `W` (subspace projectors)
+* `A` (subspace decoders)
+
+using `solve_subspaces()`.
+
+Experiments have shown that an exponential decay schedule often produces the best subspace geometries. In practice, this means recomputing relatively frequently during the early stages of training and less frequently later on.
+
+We generally do not recommend recomputing subspaces within an epoch unless extremely large datasets are being used.
+
+## Architectures and Setups That Work Well
+
+### 1. Separate Encoder / Decoder U-Net
+
+Our initial experiments used a U-Net-style architecture in which the encoder (including the bottleneck) was trained under the SPACE regime, while the decoder was trained separately on the final inference objective.
+
+This setup showed promising results for physics-guided inference tasks where conventional U-Nets often struggle to learn physically meaningful latent representations.
+
+### 2. Additional Architectures
+
+This section is currently a work in progress and may be published separately in the future.

spacelearn-0.1.0/SPACE.md

@@ -0,0 +1,190 @@
+[README](./README.md)
+
+# SPACE (Subspace Partitioning for Accessible Controlled Encodings)
+
+`SPACE-Learn` provides a utility library build on `pytorch`, that offers functions to train your Deep-Learning Models on the `Latent-SPACE` regime. The SPACE method helps create structured and easy to decode embedding spaces or explicitly guide a models internal latent space using training side information. This method encodes features that are known during training time or intermediate results directly into a models latentspace. 
+
+## Example Setup
+
+### 1. Install
+
+```bash
+pip install spacelearn
+```
+
+### 2. Example Training Setup
+
+```python
+import torch
+from torch.optim import Adam
+from collections import defaultdict
+
+from spacelearn import (
+    solve_dims,
+    solve_subspaces,
+    combined_loss,
+)
+from spacelearn.data import input_to_quantity
+from spacelearn.optim import minimal_latent_dim
+
+from my_model import Model
+from my_data import (
+    DataLoader,
+    quantity_helper_a,
+    quantity_helper_b,
+)
+
+EPOCHS = 5
+LR = 1e-3
+
+MAX_BINS = 10
+
+# target variance retained by pooling
+BIN_THRESHOLDS = 0.80
+
+# target variance retained by subspaces
+K_THRESHOLDS = {
+    "A": 0.90,
+    "B": 0.85,
+}
+
+REEVAL_EVERY = 2
+INIT_SAMPLES = 100
+
+dataloader = DataLoader()
+
+# ------------------------------------------------------------------
+# 1. Collect data for dimension estimation
+# ------------------------------------------------------------------
+
+test_data = defaultdict(list)
+samples = []
+
+for i in range(INIT_SAMPLES):
+    sample = dataloader[i]
+
+    test_data["A"].append(
+        quantity_helper_a(samples=sample)
+    )
+    test_data["B"].append(
+        quantity_helper_b(samples=sample)
+    )
+
+    samples.append(sample)
+
+test_data["A"] = torch.stack(test_data["A"])
+test_data["B"] = torch.stack(test_data["B"])
+
+samples = torch.stack(samples)
+
+# ------------------------------------------------------------------
+# 2. Estimate n and k
+# ------------------------------------------------------------------
+
+dims = solve_dims(
+    test_data,
+    max_bins=MAX_BINS,
+    bin_thresholds=BIN_THRESHOLDS,
+    k_thresholds=K_THRESHOLDS,
+    k_per_quantity=True,
+)
+
+# shared pooling resolution
+N = next(iter(dims.values()))[0]
+
+# per-quantity subspace dimensions
+K = {q: k for q, (_, k) in dims.items()}
+
+# latent dimension
+D = minimal_latent_dim(
+    K,
+    free_frac=0.10,
+)
+
+# ------------------------------------------------------------------
+# 3. Build quantity extraction helper
+# ------------------------------------------------------------------
+
+pool_helper = input_to_quantity(
+    N,
+    "avg",
+    A=quantity_helper_a,
+    B=quantity_helper_b,
+)
+
+# ------------------------------------------------------------------
+# 4. Initialize model
+# ------------------------------------------------------------------
+
+model = Model(D)
+optimizer = Adam(model.parameters(), lr=LR)
+
+# ------------------------------------------------------------------
+# 5. Training loop
+# ------------------------------------------------------------------
+
+W_prev = None
+
+for epoch in range(EPOCHS):
+
+    # periodically recompute subspaces
+    if epoch % REEVAL_EVERY == 0:
+
+        with torch.no_grad():
+            Z_ref = model(samples)
+
+        Y_ref = pool_helper(samples=samples)
+
+        WAV = solve_subspaces(
+            Z_ref,
+            Y_ref,
+            k=k,
+        )
+
+        W = WAV.W
+        A = WAV.A
+
+        if W_prev is None:
+            W_prev = {
+                q: w.clone()
+                for q, w in W.items()
+            }
+
+    for batch in dataloader:
+
+        Y = pool_helper(samples=batch)
+        Z = model(batch)
+
+        space_loss = combined_loss(
+            Z,
+            W,
+            A,
+            Y,
+            W_prev,
+        )
+
+        # task_loss = ...
+        # loss = task_loss + space_loss
+
+        optimizer.zero_grad()
+        space_loss.backward()
+        optimizer.step()
+
+    W_prev = {
+        q: w.clone()
+        for q, w in W.items()
+    }
+```
+
+
+## DOCS:
+
+[spacelearn](./docs/SPACELEARN.md)
+
+[spacelearn.settings](./docs/SETTINGS.md)
+
+[spacelearn.data](./docs/data/DATA.md)
+
+[spacelearn.loss](./docs/loss/LOSS.md)
+
+[spacelearn.optim](./docs/optim/OPTIM.md)