neuralign 0.1.0__tar.gz

neuralign-0.1.0/.github/scripts/check_pypi_release.py

@@ -0,0 +1,68 @@
+"""Decide whether a verified version is new, without hiding partial uploads."""
+
+import json
+import os
+from pathlib import Path
+import tomllib
+from urllib.error import HTTPError
+from urllib.parse import quote
+from urllib.request import Request, urlopen
+
+
+def needs_publishing(name, version, filenames):
+    """Return False only for an existing, complete, non-yanked release.
+
+    PyPI files cannot be replaced. Ordinary main updates keep their version and
+    skip publishing; incomplete releases require an explicit maintainer decision.
+    Network failures and unexpected API responses must fail the workflow.
+    """
+    url = f"https://pypi.org/pypi/{quote(name, safe='')}/{quote(version, safe='')}/json"
+    request = Request(
+        url,
+        headers={"Accept": "application/json", "User-Agent": "neuralign-release-check"},
+    )
+    try:
+        with urlopen(request, timeout=30) as response:
+            release = json.load(response)
+    except HTTPError as error:
+        if error.code == 404:
+            return True
+        raise
+
+    available = {
+        item["filename"] for item in release["urls"] if not item.get("yanked", False)
+    }
+    missing = set(filenames) - available
+    if missing:
+        raise RuntimeError(
+            f"PyPI already contains {name} {version}, but its release is incomplete "
+            f"or yanked (missing: {', '.join(sorted(missing))}). Recover the release "
+            "deliberately or bump the version; automatic publishing will not skip "
+            "individual files."
+        )
+    return False
+
+
+def main():
+    project = tomllib.loads(Path("pyproject.toml").read_text())["project"]
+    name, version = project["name"], project["version"]
+    wheels = list(Path("dist").glob("*.whl"))
+    sources = list(Path("dist").glob("*.tar.gz"))
+    if len(wheels) != 1 or len(sources) != 1:
+        raise RuntimeError("Expected exactly one verified wheel and source distribution")
+
+    publish = needs_publishing(name, version, [path.name for path in wheels + sources])
+    outputs = f"version={version}\npublish={str(publish).lower()}\n"
+    if output_file := os.environ.get("GITHUB_OUTPUT"):
+        with open(output_file, "a", encoding="utf-8") as stream:
+            stream.write(outputs)
+    status = "will be published" if publish else "is already published; skipping upload"
+    message = f"{name} {version} {status}."
+    print(message)
+    if summary_file := os.environ.get("GITHUB_STEP_SUMMARY"):
+        with open(summary_file, "a", encoding="utf-8") as stream:
+            stream.write(message + "\n")
+
+
+if __name__ == "__main__":
+    main()

neuralign-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  package:
+    name: Python ${{ matrix.python }} / ${{ matrix.dependencies }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python: "3.10"
+            dependencies: minimum
+            torch: torch==2.9.1
+            numpy: numpy==1.26.0
+          - python: "3.11"
+            dependencies: latest
+            torch: torch>=2.9.1
+            numpy: numpy>=1.26
+          - python: "3.12"
+            dependencies: latest
+            torch: torch>=2.9.1
+            numpy: numpy>=1.26
+          - python: "3.13"
+            dependencies: latest
+            torch: torch>=2.9.1
+            numpy: numpy>=1.26
+          - python: "3.14"
+            dependencies: latest
+            torch: torch>=2.9.1
+            numpy: numpy>=1.26
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Build and validate distributions
+        run: |
+          python -m pip install build twine
+          python -m build
+          python -m twine check --strict dist/*
+      - name: Install the wheel with CPU dependencies
+        env:
+          TORCH_REQUIREMENT: ${{ matrix.torch }}
+          NUMPY_REQUIREMENT: ${{ matrix.numpy }}
+        run: |
+          python -m pip install --index-url https://download.pytorch.org/whl/cpu "$TORCH_REQUIREMENT"
+          python -m pip install "$NUMPY_REQUIREMENT" dist/*.whl
+          python -m pip check
+      - name: Test the installed package
+        run: python -I -m unittest discover -s tests -v
+
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Build documentation and check generated files
+        run: |
+          python -m pip install "markdown-it-py>=3.0"
+          python docs/build.py
+          git diff --exit-code -- docs

neuralign-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,47 @@
+name: Deploy docs to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build documentation
+        run: |
+          python -m pip install "markdown-it-py>=3.0"
+          python docs/build.py
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

neuralign-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,89 @@
+name: Publish package to PyPI
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# A rerun or a second main update must not race an upload already in progress.
+concurrency:
+  group: pypi-publish
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build and verify distributions
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    outputs:
+      publish: ${{ steps.release.outputs.publish }}
+      version: ${{ steps.release.outputs.version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Build wheel and source distribution
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check --strict dist/*
+
+      - name: Install CPU PyTorch
+        run: python -m pip install --index-url https://download.pytorch.org/whl/cpu "torch>=2.9.1"
+
+      - name: Test installed wheel
+        run: |
+          python -m pip install dist/*.whl
+          python -m pip check
+          python -I -m unittest discover -s tests -v
+
+      - name: Test installed source distribution
+        run: |
+          python -m pip uninstall --yes neuralign
+          python -m pip install dist/*.tar.gz
+          python -m pip check
+          python -I -m unittest discover -s tests -v
+
+      - name: Check whether this version needs publishing
+        id: release
+        run: python .github/scripts/check_pypi_release.py
+
+      - name: Upload verified distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-distributions
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 14
+
+  publish:
+    name: Publish new version
+    needs: build
+    if: github.ref == 'refs/heads/main' && needs.build.outputs.publish == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/neuralign/${{ needs.build.outputs.version }}/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download verified distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: python-distributions
+          path: dist/
+
+      # No checkout or package execution in the job with publishing permission.
+      # Configure this workflow and the pypi environment as a Trusted Publisher.
+      - name: Publish distributions with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1

neuralign-0.1.0/CITATION.cff

@@ -0,0 +1,36 @@
+cff-version: 1.2.0
+message: "If you use Neuralign, please cite this software and the associated manuscript."
+title: "Neuralign"
+type: software
+license: MIT
+version: 0.1.0
+repository-code: "https://github.com/MiklosKralik/neuralign"
+authors:
+  - family-names: Králik
+    given-names: Miklós
+  - family-names: Tinelli
+    given-names: Sasha
+  - family-names: Kozloski
+    given-names: James
+  - family-names: Ponte Costa
+    given-names: Rui
+  - family-names: Sharott
+    given-names: Andrew
+  - family-names: Peach
+    given-names: Robert L.
+preferred-citation:
+  type: unpublished
+  title: "Identifying aligned tensor decompositions across heterogeneous neural datasets"
+  authors:
+    - family-names: Králik
+      given-names: Miklós
+    - family-names: Tinelli
+      given-names: Sasha
+    - family-names: Kozloski
+      given-names: James
+    - family-names: Ponte Costa
+      given-names: Rui
+    - family-names: Sharott
+      given-names: Andrew
+    - family-names: Peach
+      given-names: Robert L.

neuralign-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neuralign contributors
+
+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.

neuralign-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: neuralign
+Version: 0.1.0
+Summary: Joint tensor decomposition and alignment of trial-resolved neural recordings
+Keywords: computational neuroscience,tensor decomposition,neural population dynamics,representation alignment
+Author: Miklós Králik, Sasha Tinelli, James Kozloski, Rui Ponte Costa, Andrew Sharott, Robert L. Peach
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: numpy>=1.26
+Requires-Dist: opt-einsum>=3.4.0
+Requires-Dist: torch>=2.9.1
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: markdown-it-py>=3.0 ; extra == 'docs'
+Requires-Dist: matplotlib>=3.8 ; extra == 'examples'
+Requires-Python: >=3.10
+Project-URL: Documentation, https://mikloskralik.github.io/neuralign/
+Project-URL: Repository, https://github.com/MiklosKralik/neuralign
+Project-URL: Issues, https://github.com/MiklosKralik/neuralign/issues
+Provides-Extra: docs
+Provides-Extra: examples
+Description-Content-Type: text/markdown
+
+# <img src="https://raw.githubusercontent.com/MiklosKralik/neuralign/main/docs/assets/neuralign-mark.png" width="36" alt="" /> Neuralign
+
+Find shared activity patterns across neural recordings, with a factor for each neuron and each trial.
+
+[![Neuralign model overview](https://raw.githubusercontent.com/MiklosKralik/neuralign/main/docs/assets/neuralign-overview.png)](https://raw.githubusercontent.com/MiklosKralik/neuralign/main/docs/assets/neuralign-overview.pdf)
+
+## Install
+
+Python 3.10 or later. From PyPI, after the first release:
+
+```bash
+python -m pip install neuralign
+```
+
+Or directly from GitHub:
+
+```bash
+python -m pip install git+https://github.com/MiklosKralik/neuralign.git
+```
+
+## Quickstart
+
+This example generates its own data:
+
+```python
+from neuralign import NeuralignModel
+from neuralign.simulation import simulate_sessions
+
+sessions, _ = simulate_sessions(seed=42)
+factors = NeuralignModel(sessions, rank=2, max_iter=500, seed=42).fit("cpu")
+
+time_factors = factors.V                       # time × components
+neuron_factors = factors[0].neuron_factors       # neurons × components
+trial_factors = factors[0].trial_factors         # trials × components
+```
+
+For your own recordings, pass a list of arrays in **neurons × time × trials** order. Sessions may have different neuron and trial counts, but must share time bins.
+
+[Documentation](https://mikloskralik.github.io/neuralign/) · [Use your recordings](https://mikloskralik.github.io/neuralign/getting-started.html) · [Plotting example](https://github.com/MiklosKralik/neuralign/blob/main/examples/quickstart.py)
+
+## Paper
+
+Neuralign is described in *Identifying aligned tensor decompositions across heterogeneous neural datasets*.
+
+Please cite the software and manuscript when using Neuralign in research. [Citation](https://github.com/MiklosKralik/neuralign/blob/main/CITATION.cff) · [MIT License](https://github.com/MiklosKralik/neuralign/blob/main/LICENSE).

neuralign-0.1.0/README.md

@@ -0,0 +1,45 @@
+# <img src="https://raw.githubusercontent.com/MiklosKralik/neuralign/main/docs/assets/neuralign-mark.png" width="36" alt="" /> Neuralign
+
+Find shared activity patterns across neural recordings, with a factor for each neuron and each trial.
+
+[![Neuralign model overview](https://raw.githubusercontent.com/MiklosKralik/neuralign/main/docs/assets/neuralign-overview.png)](https://raw.githubusercontent.com/MiklosKralik/neuralign/main/docs/assets/neuralign-overview.pdf)
+
+## Install
+
+Python 3.10 or later. From PyPI, after the first release:
+
+```bash
+python -m pip install neuralign
+```
+
+Or directly from GitHub:
+
+```bash
+python -m pip install git+https://github.com/MiklosKralik/neuralign.git
+```
+
+## Quickstart
+
+This example generates its own data:
+
+```python
+from neuralign import NeuralignModel
+from neuralign.simulation import simulate_sessions
+
+sessions, _ = simulate_sessions(seed=42)
+factors = NeuralignModel(sessions, rank=2, max_iter=500, seed=42).fit("cpu")
+
+time_factors = factors.V                       # time × components
+neuron_factors = factors[0].neuron_factors       # neurons × components
+trial_factors = factors[0].trial_factors         # trials × components
+```
+
+For your own recordings, pass a list of arrays in **neurons × time × trials** order. Sessions may have different neuron and trial counts, but must share time bins.
+
+[Documentation](https://mikloskralik.github.io/neuralign/) · [Use your recordings](https://mikloskralik.github.io/neuralign/getting-started.html) · [Plotting example](https://github.com/MiklosKralik/neuralign/blob/main/examples/quickstart.py)
+
+## Paper
+
+Neuralign is described in *Identifying aligned tensor decompositions across heterogeneous neural datasets*.
+
+Please cite the software and manuscript when using Neuralign in research. [Citation](https://github.com/MiklosKralik/neuralign/blob/main/CITATION.cff) · [MIT License](https://github.com/MiklosKralik/neuralign/blob/main/LICENSE).

neuralign-0.1.0/docs/api.html

@@ -0,0 +1,133 @@
+<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>API · Neuralign</title><link rel="icon" href="assets/neuralign-mark.svg" type="image/svg+xml"><link rel="stylesheet" href="style.css"></head>
+<body><nav aria-label="Main navigation"><a href="index.html" >Neuralign</a> <a href="getting-started.html" >Your recordings</a> <a href="model-and-outputs.html" >Outputs</a> <a href="api.html" aria-current=page>API</a> <a href="reproducibility.html" >Save a fit</a></nav><main><h1>API reference</h1>
+<pre><code class="language-python">from neuralign import NeuralignConfig, NeuralignModel, NeuralignFactors
+</code></pre>
+<h2>Fitting settings</h2>
+<p>Pass settings through <code>NeuralignConfig</code> or directly to <code>NeuralignModel</code>.</p>
+<table>
+<thead>
+<tr>
+<th>Setting</th>
+<th>Default</th>
+<th>Purpose</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>rank</code></td>
+<td><code>4</code></td>
+<td>Number of components</td>
+</tr>
+<tr>
+<td><code>max_iter</code></td>
+<td><code>2000</code></td>
+<td>Maximum optimisation steps</td>
+</tr>
+<tr>
+<td><code>lr</code></td>
+<td><code>0.01</code></td>
+<td>Learning rate</td>
+</tr>
+<tr>
+<td><code>patience</code></td>
+<td><code>100</code></td>
+<td>Early-stopping patience</td>
+</tr>
+<tr>
+<td><code>tol</code></td>
+<td><code>1e-6</code></td>
+<td>Early-stopping improvement threshold</td>
+</tr>
+<tr>
+<td><code>seed</code></td>
+<td><code>None</code></td>
+<td>Random seed</td>
+</tr>
+<tr>
+<td><code>progress</code></td>
+<td><code>True</code></td>
+<td>Display fitting progress</td>
+</tr>
+<tr>
+<td><code>lambda_tensor_reconstruction</code></td>
+<td><code>1.0</code></td>
+<td>Reconstruction-loss weight</td>
+</tr>
+<tr>
+<td><code>lambda_procrustes</code></td>
+<td><code>1.0</code></td>
+<td>Alignment-loss weight</td>
+</tr>
+<tr>
+<td><code>non_negative</code></td>
+<td><code>False</code></td>
+<td>Nonnegative factors</td>
+</tr>
+<tr>
+<td><code>loss_type</code></td>
+<td><code>&quot;frobenius&quot;</code></td>
+<td>Also <code>&quot;poisson&quot;</code> or <code>&quot;poisson_log&quot;</code></td>
+</tr>
+</tbody>
+</table>
+<p>The default Frobenius loss fits continuous activity. Count losses require nonnegative counts: <code>&quot;poisson&quot;</code> models rates and <code>&quot;poisson_log&quot;</code> models log-rates. For log-Poisson fits, exponentiate <code>reconstructed_tensor()</code> to obtain rates.</p>
+<h2>NeuralignModel</h2>
+<pre><code class="language-python">NeuralignModel(tensor_sequence, trial_labels=None, trial_mask=None,
+               config=None, **settings)
+model.fit(device=&quot;cpu&quot;)
+</code></pre>
+<p><code>fit</code> returns <code>NeuralignFactors</code>. Inputs use neurons × time × trials and share a time axis.</p>
+<p><code>trial_labels</code> provides one label sequence per session. Alignment uses trial means without labels and condition means with labels.</p>
+<p><code>trial_mask</code> provides one Boolean array per session. <strong>True excludes a trial from alignment only:</strong> it still contributes to reconstruction. Each session needs an unmasked trial.</p>
+<h2>NeuralignFactors</h2>
+<table>
+<thead>
+<tr>
+<th>Method</th>
+<th>Behaviour</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>len(factors)</code></td>
+<td>Number of sessions</td>
+</tr>
+<tr>
+<td><code>factors[i]</code> or <code>factors.session(i)</code></td>
+<td>Session factors</td>
+</tr>
+<tr>
+<td><code>factors.to(device)</code></td>
+<td>Move tensors to a device</td>
+</tr>
+<tr>
+<td><code>factors.save(path)</code></td>
+<td>Save factors, configuration and metadata</td>
+</tr>
+<tr>
+<td><code>NeuralignFactors.load(path, map_location=&quot;cpu&quot;)</code></td>
+<td>Load a saved fit</td>
+</tr>
+<tr>
+<td><code>factors.partial_fit(...)</code></td>
+<td>Add sessions with shared factors frozen</td>
+</tr>
+</tbody>
+</table>
+<p><code>partial_fit(new_session, device=&quot;cpu&quot;, **settings)</code> returns a copy with new sessions appended. It fits their session factors while freezing <code>w</code>, <code>V</code>, <code>H</code> and condition prototypes. New sessions must share the fitted time axis. Recognised labels anchor alignment; sessions without recognised labels use trial means. Supervised adaptation applies a small condition-centroid penalty; <code>lambda_condition_centroid=0.0</code> disables it.</p>
+<h2>Session outputs</h2>
+<p>Access a session with <code>session = factors[i]</code>. See <a href="model-and-outputs.html">model outputs</a> for its factor properties and shapes.</p>
+<pre><code class="language-python">session.reconstructed_tensor(components=None, *, normalized=False)
+session.reconstructed_latent_tensor(components=None, *, normalized=False)
+session.latent_trajectories(layout=&quot;ktr&quot;, *, components=None, normalized=False)
+session.projected_trajectories(Z, layout=&quot;ktr&quot;)
+</code></pre>
+<p>For reconstruction methods, <code>components</code> accepts an index or a list of indices; <code>None</code> includes all components. <code>normalized=True</code> uses unit global weights.</p>
+<h2>Simulation</h2>
+<pre><code class="language-python">from neuralign.simulation import simulate_sessions
+sessions, truth = simulate_sessions(n_sessions=4, n_time=64, noise_std=0.15, seed=42)
+</code></pre>
+<p>Generates rank-two recordings with different neuron/trial counts. <code>noise_std</code> is relative to the clean signal's standard deviation; <code>truth</code> contains the generating factors.</p>
+</main></body></html>

neuralign-0.1.0/docs/api.md

@@ -0,0 +1,74 @@
+# API reference
+
+```python
+from neuralign import NeuralignConfig, NeuralignModel, NeuralignFactors
+```
+
+## Fitting settings
+
+Pass settings through `NeuralignConfig` or directly to `NeuralignModel`.
+
+| Setting | Default | Purpose |
+| --- | --- | --- |
+| `rank` | `4` | Number of components |
+| `max_iter` | `2000` | Maximum optimisation steps |
+| `lr` | `0.01` | Learning rate |
+| `patience` | `100` | Early-stopping patience |
+| `tol` | `1e-6` | Early-stopping improvement threshold |
+| `seed` | `None` | Random seed |
+| `progress` | `True` | Display fitting progress |
+| `lambda_tensor_reconstruction` | `1.0` | Reconstruction-loss weight |
+| `lambda_procrustes` | `1.0` | Alignment-loss weight |
+| `non_negative` | `False` | Nonnegative factors |
+| `loss_type` | `"frobenius"` | Also `"poisson"` or `"poisson_log"` |
+
+The default Frobenius loss fits continuous activity. Count losses require nonnegative counts: `"poisson"` models rates and `"poisson_log"` models log-rates. For log-Poisson fits, exponentiate `reconstructed_tensor()` to obtain rates.
+
+## NeuralignModel
+
+```python
+NeuralignModel(tensor_sequence, trial_labels=None, trial_mask=None,
+               config=None, **settings)
+model.fit(device="cpu")
+```
+
+`fit` returns `NeuralignFactors`. Inputs use neurons × time × trials and share a time axis.
+
+`trial_labels` provides one label sequence per session. Alignment uses trial means without labels and condition means with labels.
+
+`trial_mask` provides one Boolean array per session. **True excludes a trial from alignment only:** it still contributes to reconstruction. Each session needs an unmasked trial.
+
+## NeuralignFactors
+
+| Method | Behaviour |
+| --- | --- |
+| `len(factors)` | Number of sessions |
+| `factors[i]` or `factors.session(i)` | Session factors |
+| `factors.to(device)` | Move tensors to a device |
+| `factors.save(path)` | Save factors, configuration and metadata |
+| `NeuralignFactors.load(path, map_location="cpu")` | Load a saved fit |
+| `factors.partial_fit(...)` | Add sessions with shared factors frozen |
+
+`partial_fit(new_session, device="cpu", **settings)` returns a copy with new sessions appended. It fits their session factors while freezing `w`, `V`, `H` and condition prototypes. New sessions must share the fitted time axis. Recognised labels anchor alignment; sessions without recognised labels use trial means. Supervised adaptation applies a small condition-centroid penalty; `lambda_condition_centroid=0.0` disables it.
+
+## Session outputs
+
+Access a session with `session = factors[i]`. See [model outputs](model-and-outputs.md) for its factor properties and shapes.
+
+```python
+session.reconstructed_tensor(components=None, *, normalized=False)
+session.reconstructed_latent_tensor(components=None, *, normalized=False)
+session.latent_trajectories(layout="ktr", *, components=None, normalized=False)
+session.projected_trajectories(Z, layout="ktr")
+```
+
+For reconstruction methods, `components` accepts an index or a list of indices; `None` includes all components. `normalized=True` uses unit global weights.
+
+## Simulation
+
+```python
+from neuralign.simulation import simulate_sessions
+sessions, truth = simulate_sessions(n_sessions=4, n_time=64, noise_std=0.15, seed=42)
+```
+
+Generates rank-two recordings with different neuron/trial counts. `noise_std` is relative to the clean signal's standard deviation; `truth` contains the generating factors.