Efficiencies

.github/workflows/benchmark.yml

@@ -0,0 +1,58 @@
+name: Performance Benchmark
+
+on:
+  push:
+    branches: [ '**' ]
+  pull_request:
+    branches: [ 'main' ]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  benchmark:
+    name: RATS Benchmark (${{ matrix.os }}, ${{ matrix.ref_name }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        ref: ["${{ github.sha }}", "5eaa1c6a82eb0a316ff2a6911e0ef7379add0bad"]
+        include:
+          - ref: "${{ github.sha }}"
+            ref_name: "Current HEAD"
+          - ref: "5eaa1c6a82eb0a316ff2a6911e0ef7379add0bad"
+            ref_name: "5eaa1c6 (Joshua V1)"
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 0
+
+      - name: Overlay src/ from Comparison Ref
+        if: matrix.ref != github.sha
+        run: |
+          git fetch origin ${{ matrix.ref }} --depth=1
+          git checkout FETCH_HEAD -- src/
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Install Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[test]
+
+      - name: Run Benchmark
+        run: |
+          echo "## RATS Performance Benchmarks (${{ matrix.os }})" >> $GITHUB_STEP_SUMMARY
+          echo "Commit: ${{ matrix.ref_name }} (${{ matrix.ref }})" >> $GITHUB_STEP_SUMMARY
+          echo "Dataset: Klein Bottle (4D)" >> $GITHUB_STEP_SUMMARY
+          python tests/scripts/benchmark.py >> $GITHUB_STEP_SUMMARY

.github/workflows/ci.yml

@@ -29,8 +29,8 @@ jobs:
 
     - name: Install Dependencies
       run: |
-        pip install --upgrade pip
-        pip install -e .[test]
+        python -m pip install --upgrade pip
+        python -m pip install -e .[test]
 
     - name: Set Fast Mode Flag
       id: set-flag

.gitignore

@@ -1,5 +1,6 @@
 src/pyRATS/__pycache__/
 src/pyRATS.egg-info
+tests/data
 .vscode
 .DS_Store
 __pycache__

README.md

@@ -33,7 +33,7 @@ import datasets, vis
 X, labels, _ = datasets.Datasets().kleinbottle4d(n=5000)
 
 # create a RATS object projecting the data to 2d while tearing the manifold
-model = rats.RATS(d=2, k=28, eta_min=5, to_tear=True)
+model = rats.RATS(n_components=2, n_neighbors=28, min_cluster_size=5, tear=True)
 y = model.fit_transform(X)
 
 # compute the gluing instructions along the tear
@@ -61,6 +61,15 @@ python -m http.server 8000
 ```
 and opening http://localhost:8000 in your browser.
 
+# Memory Management
+`pyRATS` implements dynamic chunking to prevent memory spikes on large or high-dimensional datasets. By default, it attempts to use up to 75% of available system RAM. This measurement can fail and defaults to 4GB otherwise. If you need to explicitly set memory usage, set the `PYRATS_MEMORY_LIMIT` environment variable (in bytes):
+
+```bash
+# Set pyRATS memory usage to 40GB
+export PYRATS_MEMORY_LIMIT=42949672960
+python your_script.py
+```
+
 
 Citation
 ----------

examples/barbell_example.ipynb

@@ -58,14 +58,14 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "buml_obj = rats.RATS(\n",
-    "    d=2,\n",
-    "    k=28,\n",
-    "    eta_min=5,\n",
-    "    to_tear=True,\n",
+    "model = rats.RATS(\n",
+    "    n_components=2,\n",
+    "    n_neighbors=28,\n",
+    "    min_cluster_size=5,\n",
+    "    tear=True,\n",
     ")\n",
     "\n",
-    "y = buml_obj.fit_transform(X=X)\n",
+    "y = model.fit_transform(X=X)\n",
     "y"
    ]
   },
@@ -85,7 +85,7 @@
    "outputs": [],
    "source": [
     "tear_color_eig_inds = [0,1,2] # interior has green color so assigned smallest value of i to g-channel\n",
-    "color_of_pts_on_tear = buml_obj.compute_color_of_pts_on_tear(\n",
+    "color_of_pts_on_tear = model.compute_color_of_pts_on_tear(\n",
     "    y,\n",
     "    tear_color_eig_inds\n",
     ")\n",
@@ -129,4 +129,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

examples/curvedtorus_example.ipynb

@@ -58,17 +58,17 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "buml_obj = rats.RATS(\n",
-    "    d=2,\n",
-    "    k=21,\n",
-    "    eta_min=5,\n",
+    "model = rats.RATS(\n",
+    "    n_components=2,\n",
+    "    n_neighbors=21,\n",
+    "    min_cluster_size=5,\n",
     "    nu=3,\n",
-    "    max_iter=40,\n",
-    "    to_tear=True,\n",
-    "    cost_fn_name='distortion'\n",
+    "    n_iter=40,\n",
+    "    tear=True,\n",
+    "    cost_function='distortion'\n",
     ")\n",
     "\n",
-    "y = buml_obj.fit_transform(X=X)\n",
+    "y = model.fit_transform(X=X)\n",
     "y"
    ]
   },
@@ -88,7 +88,7 @@
    "outputs": [],
    "source": [
     "tear_color_eig_inds = [6, 1, 4] # interior has green color so assigned smallest value of i to g-channel\n",
-    "color_of_pts_on_tear = buml_obj.compute_color_of_pts_on_tear(\n",
+    "color_of_pts_on_tear = model.compute_color_of_pts_on_tear(\n",
     "    y,\n",
     "    tear_color_eig_inds\n",
     ")\n",
@@ -132,4 +132,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

examples/kleinbottle_example.ipynb

@@ -7,7 +7,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%pip install git+https://github.com/Mishne-Lab/pyRATS\n",
+    "# %pip install git+https://github.com/Mishne-Lab/pyRATS\n",
     "# if not already installed on the system:\n",
     "# %pip install pandas imageio seaborn matplotlib"
    ]
@@ -19,9 +19,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "import sys\n",
+    "sys.path.insert(0, '../src/')\n",
+    "\n",
     "from matplotlib import pyplot as plt\n",
     "\n",
-    "from pyRATS import rats\n",
+    "from pyRATS import rats, global_distortion\n",
     "import datasets, vis"
    ]
   },
@@ -58,17 +61,36 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "buml_obj = rats.RATS(\n",
-    "    d=2,\n",
-    "    k=28,\n",
-    "    eta_min=5,\n",
-    "    to_tear=True,\n",
+    "model = rats.RATS(\n",
+    "    n_components=2,\n",
+    "    n_neighbors=28,\n",
+    "    min_cluster_size=5,\n",
+    "    tear=True,\n",
     ")\n",
     "\n",
-    "y = buml_obj.fit_transform(X=X)\n",
+    "y = model.fit_transform(X=X)\n",
     "y"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0fdf51f9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "n_nbrs = global_distortion.get_n_nbrs_for_distortion_analysis(X)\n",
+    "\n",
+    "global_distortion.compute_global_distortion(\n",
+    "    X,\n",
+    "    y,\n",
+    "    n_nbrs,\n",
+    "    buml_obj,\n",
+    "    metric=\"euclidean\",\n",
+    "    max_crossings=20,\n",
+    ")"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -77,7 +99,7 @@
    "outputs": [],
    "source": [
     "tear_color_eig_inds = [7, 2, 4]\n",
-    "color_of_pts_on_tear = buml_obj.compute_color_of_pts_on_tear(\n",
+    "color_of_pts_on_tear = model.compute_color_of_pts_on_tear(\n",
     "    y,\n",
     "    tear_color_eig_inds, \n",
     ")\n",
@@ -90,14 +112,6 @@
     ")\n",
     "plt.show()"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "c9b56299",
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {
@@ -121,4 +135,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

examples/small_noisyswissroll3_example.ipynb

@@ -58,15 +58,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "buml_obj = rats.RATS(\n",
-    "    d=2,\n",
-    "    k=28,\n",
-    "    eta_min=5,\n",
-    "    to_tear=True,\n",
-    "    cost_fn_name='alignment'\n",
+    "model = rats.RATS(\n",
+    "    n_components=2,\n",
+    "    n_neighbors=28,\n",
+    "    min_cluster_size=5,\n",
+    "    tear=True,\n",
+    "    cost_function='alignment'\n",
     ")\n",
     "\n",
-    "y = buml_obj.fit_transform(X=X)\n",
+    "y = model.fit_transform(X=X)\n",
     "y"
    ]
   },
@@ -78,7 +78,7 @@
    "outputs": [],
    "source": [
     "tear_color_eig_inds = [0, 1, 2] # interior has green color so assigned smallest value of i to g-channel\n",
-    "color_of_pts_on_tear = buml_obj.compute_color_of_pts_on_tear(\n",
+    "color_of_pts_on_tear = model.compute_color_of_pts_on_tear(\n",
     "    y,\n",
     "    tear_color_eig_inds, \n",
     ")\n",
@@ -122,4 +122,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

examples/small_spherewithhole_example.ipynb

@@ -58,14 +58,14 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "buml_obj = rats.RATS(\n",
-    "    d=2,\n",
-    "    k=28,\n",
-    "    eta_min=5,\n",
-    "    to_tear=True,\n",
+    "model = rats.RATS(\n",
+    "    n_components=2,\n",
+    "    n_neighbors=28,\n",
+    "    min_cluster_size=5,\n",
+    "    tear=True,\n",
     ")\n",
     "\n",
-    "y = buml_obj.fit_transform(X=X)\n",
+    "y = model.fit_transform(X=X)\n",
     "y"
    ]
   },
@@ -87,7 +87,7 @@
     "figsize = (3,3)\n",
     "\n",
     "tear_color_eig_inds = [7, 1, 2]\n",
-    "color_of_pts_on_tear = buml_obj.compute_color_of_pts_on_tear(\n",
+    "color_of_pts_on_tear = model.compute_color_of_pts_on_tear(\n",
     "    y,\n",
     "    tear_color_eig_inds, \n",
     ")\n",
@@ -131,4 +131,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

examples/small_swissrollwithhole.ipynb

@@ -58,14 +58,14 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "buml_obj = rats.RATS(\n",
-    "    d=2,\n",
-    "    k=28,\n",
-    "    eta_min=5,\n",
-    "    to_tear=True,\n",
+    "model = rats.RATS(\n",
+    "    n_components=2,\n",
+    "    n_neighbors=28,\n",
+    "    min_cluster_size=5,\n",
+    "    tear=True,\n",
     ")\n",
     "\n",
-    "y = buml_obj.fit_transform(X=X)\n",
+    "y = model.fit_transform(X=X)\n",
     "y"
    ]
   },
@@ -85,7 +85,7 @@
    "outputs": [],
    "source": [
     "tear_color_eig_inds = [0, 1, 2] # interior has green color so assigned smallest value of i to g-channel\n",
-    "color_of_pts_on_tear = buml_obj.compute_color_of_pts_on_tear(\n",
+    "color_of_pts_on_tear = model.compute_color_of_pts_on_tear(\n",
     "    y,\n",
     "    tear_color_eig_inds, \n",
     ")\n",
@@ -129,4 +129,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}