diffct 2.5.0__tar.gz → 2.5.1__tar.gz

{diffct-2.5.0 → diffct-2.5.1}/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.5.1] - 2026-11-07
+
+### Fixed
+
+- Saving a solver checkpoint into a step that already exists raises a clear
+  `ValueError` that names the existing directory, instead of a bare
+  `FileExistsError`. The existing checkpoint is not changed. Use a new
+  `checkpoint_directory`, or pass `resume=` to continue from it. Thanks to
+  @cslht11 ([#63](https://github.com/sypsyp97/diffct/pull/63)).
+- `random_trajectory_3d(seed=...)` draws its noise from a private generator
+  and no longer reseeds the process-wide PyTorch generator. Seeded
+  trajectories are unchanged. Thanks to @cslht11
+  ([#64](https://github.com/sypsyp97/diffct/pull/64)).
+
+### Changed
+
+- CPU tests check the FBP, FDK and short-scan Parker accuracy bounds on the
+  portable backend, so CI covers them without a GPU. Thanks to @cslht11
+  ([#65](https://github.com/sypsyp97/diffct/pull/65)).
+- A `.mailmap` joins the commits of one contributor under one name
+  ([#62](https://github.com/sypsyp97/diffct/pull/62)).
+
+### Documentation
+
+- Semantic search on the documentation site is off by default. The
+  embedding model (about 377 MB) downloads only after the visitor enables it
+  ([#66](https://github.com/sypsyp97/diffct/pull/66)).
+
 ## [2.5.0] - 2026-10-26
 
 ### Added

{diffct-2.5.0 → diffct-2.5.1}/CITATION.cff

@@ -14,8 +14,8 @@ authors:
     given-names: Yipeng
     email: yipeng.sun@fau.de
     alias: sypsyp97
-version: 2.5.0
-date-released: "2026-10-26"
+version: 2.5.1
+date-released: "2026-11-07"
 license: Apache-2.0
 repository-code: "https://github.com/sypsyp97/diffct"
 url: "https://sypsyp97.github.io/diffct/"

{diffct-2.5.0 → diffct-2.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: diffct
-Version: 2.5.0
+Version: 2.5.1
 Summary: Differentiable CT projection and reconstruction: precision modes, streaming, distributed execution and geometry gradients
 Project-URL: Homepage, https://github.com/sypsyp97/diffct
 Project-URL: Documentation, https://sypsyp97.github.io/diffct/

{diffct-2.5.0 → diffct-2.5.1}/diffct/__init__.py

@@ -64,7 +64,7 @@ try:
 except ImportError:
     pass
 
-__version__ = '2.5.0'
+__version__ = '2.5.1'
 
 __all__ = [
     'Projector',

{diffct-2.5.0 → diffct-2.5.1}/diffct/_solver_state.py

@@ -288,6 +288,11 @@ def save_checkpoint(operator, directory, states, metadata, iteration, history, m
         step = Path(directory).resolve() / f"step-{iteration:06d}"
         step.mkdir(parents=True, exist_ok=True)
         rank = step / f"rank-{getattr(operator, 'rank', 0):05d}"
+        if rank.exists():
+            # Replacing a published step in place could destroy it on a
+            # failed write, and ranks cannot roll back together.
+            raise ValueError(f"checkpoint {rank} already exists; use a new checkpoint_directory "
+                             "or pass resume= to continue from it")
         rank.mkdir()
         for name, source in states.items():
             source = TensorStore(source.detach()) if isinstance(source, torch.Tensor) else source

{diffct-2.5.0 → diffct-2.5.1}/diffct/geometry.py

@@ -274,18 +274,24 @@ def random_trajectory_3d(n_views, sid_mean, sdd_mean, sid_std=0.0, pos_std=0.0,
     """
     import math
 
-    if seed is not None:
-        torch.manual_seed(seed)
-
     # Start with circular trajectory
     src_pos, det_center, det_u_vec, det_v_vec = circular_trajectory_3d(
         n_views, sid_mean, sdd_mean, device=device, dtype=dtype
     )
 
+    # Angle tensors override the requested device. Keep seeded draws on that
+    # device without changing any process-wide RNG state.
+    generator = None
+    if seed is not None:
+        # No fallback stream: a different generator would change the values.
+        generator = torch.Generator(device=src_pos.device)
+        # Match torch.manual_seed's conversion of bool, NumPy and tensor seeds.
+        generator.manual_seed(int(seed))
+
     # Add random perturbations
     if sid_std > 0.0:
         # Random SID variations
-        sid_perturbations = torch.randn(n_views, device=device, dtype=dtype) * sid_std
+        sid_perturbations = torch.randn(n_views, device=device, dtype=dtype, generator=generator) * sid_std
         sdd_perturbations = sid_perturbations.clone()  # Keep SDD-SID distance approximately constant
 
         # Compute angles from existing positions
@@ -306,12 +312,12 @@ def random_trajectory_3d(n_views, sid_mean, sdd_mean, sid_std=0.0, pos_std=0.0,
 
     if pos_std > 0.0:
         # Random 3D position offsets
-        src_pos += torch.randn_like(src_pos) * pos_std
-        det_center += torch.randn_like(det_center) * pos_std
+        src_pos += torch.empty_like(src_pos).normal_(generator=generator) * pos_std
+        det_center += torch.empty_like(det_center).normal_(generator=generator) * pos_std
 
     if angle_std > 0.0:
         # Random angular perturbations (rotate detector orientation)
-        angle_perturbations = torch.randn(n_views, device=device, dtype=dtype) * angle_std
+        angle_perturbations = torch.randn(n_views, device=device, dtype=dtype, generator=generator) * angle_std
         cos_perturb = torch.cos(angle_perturbations)
         sin_perturb = torch.sin(angle_perturbations)
 

{diffct-2.5.0 → diffct-2.5.1}/docs/search/tests/full-model.spec.mjs

@@ -7,7 +7,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { chromium } from '@playwright/test';
-import { test, expect, landingUI, typeQuery, FULL_MODEL } from './harness.mjs';
+import { test, expect, landingUI, typeQuery, enableSemanticButton, FULL_MODEL } from './harness.mjs';
 
 const HUB = /(^|\.)(huggingface\.co|hf\.co)$/;
 
@@ -34,6 +34,7 @@ test('real model: semantic results, then a reload with no second download', asyn
     await page.goto('/index.html');
     let ui = landingUI(page);
     await typeQuery(ui.input, 'how do I use a curved detector');
+    await enableSemanticButton(ui.host).click();
     let lb = await ui.listbox.locator();
     await expect(lb.getByText(/^(Semantic|Both)$/).first()).toBeVisible({ timeout: 25 * 60_000 });
     const first = downloads();

{diffct-2.5.0 → diffct-2.5.1}/docs/search/tests/harness.mjs

@@ -255,6 +255,19 @@ export class FakeHub extends EventEmitter {
 
 // ---- page helpers -------------------------------------------------------------------------
 
+/** Seed consent without overwriting choices made during the test or on reload. */
+export async function seedSemanticPreference(context) {
+  await context.addInitScript(() => {
+    if (localStorage.getItem('diffct-search') === null) {
+      localStorage.setItem('diffct-search', JSON.stringify({ semantic: 'on' }));
+    }
+  });
+}
+
+export function enableSemanticButton(host) {
+  return host.getByRole('button', { name: 'Enable semantic search (about 377 MB)', exact: true });
+}
+
 export function landingUI(page) {
   const input = page.locator('.landing-search input[name="q"]');
   return { input, host: page.locator('.landing-search .srch-host'), listbox: listboxOf(input) };
@@ -418,7 +431,7 @@ export async function routeFakeHub(context, hub) {
 
 /**
  * The results that `query` shows in a fresh browser context, as a reference.
- * mode 'keyword': the model download never finishes, so only keyword results show.
+ * mode 'keyword': a fresh visitor has not enabled semantic search.
  * mode 'semantic': the model loads and the semantic answer for `query` merges in.
  * where: 'landing' (index.html) or 'dialog' (quickstart.html, Ctrl+K dialog).
  */
@@ -426,7 +439,7 @@ export async function reference(browser, server, query, mode, where = 'landing')
   const context = await browser.newContext({ baseURL: server.origin });
   const hub = new FakeHub();
   await routeFakeHub(context, hub);
-  if (mode === 'keyword') hub.hold('onnx/model_quantized.onnx');
+  if (mode === 'semantic') await seedSemanticPreference(context);
   try {
     const page = await context.newPage();
     let ui;
@@ -451,6 +464,11 @@ export async function reference(browser, server, query, mode, where = 'landing')
 // ---- fixtures -----------------------------------------------------------------------------
 
 export const test = base.extend({
+  semanticSearch: [false, { option: true }],
+  page: async ({ page, semanticSearch }, use) => {
+    if (semanticSearch) await seedSemanticPreference(page.context());
+    await use(page);
+  },
   server: [async ({}, use) => {
     const server = await startServer(process.env.DOCS_HTML);
     await use(server);

{diffct-2.5.0 → diffct-2.5.1}/docs/search/tests/item1-ordering.spec.mjs

@@ -5,6 +5,8 @@ import {
   test, expect, landingUI, dialogUI, typeQuery, snapshot, stableSnapshot, reference, sleep,
 } from './harness.mjs';
 
+test.use({ semanticSearch: true });
+
 test.describe('item 1: ordering', () => {
   test('slow semantic answer of an older query does not replace the newer query results', async ({ browser, page, site, hub }) => {
     const Q1 = 'cone beam geometry';

{diffct-2.5.0 → diffct-2.5.1}/docs/search/tests/item2-single-load.spec.mjs

@@ -5,6 +5,8 @@ import {
   test, expect, dialogUI, landingUI, typeQuery, stableSnapshot, trackWorkers, sleep,
 } from './harness.mjs';
 
+test.use({ semanticSearch: true });
+
 const WEIGHTS = 'onnx/model_quantized.onnx';
 const FILES = ['onnx/model_quantized.onnx_data', 'tokenizer.json', 'tokenizer_config.json'];
 
@@ -58,10 +60,16 @@ test.describe('item 2: single model load', () => {
     await site.waitProbe('embed', (p) => p.text.endsWith('fan beam'));
     await stableSnapshot(ui.listbox);
     const before = hub.downloadLog().length;
+    await expect.poll(() => page.evaluate(() => JSON.parse(localStorage.getItem('diffct-search')))).toMatchObject({
+      semantic: 'on', loaded: true,
+    });
     const sessionsBefore = site.probes('session').length;
 
     await page.reload();
     const again = landingUI(page);
+    await again.input.focus();
+    await expect.poll(() => site.probes('session').length).toBe(sessionsBefore + 1);
+    await expect(again.input).toHaveValue('');
     await typeQuery(again.input, 'cone beam');
     await site.waitProbe('embed', (p) => p.text.endsWith('cone beam'));
     await stableSnapshot(again.listbox);

{diffct-2.5.0 → diffct-2.5.1}/docs/search/tests/item3-cancel.spec.mjs

@@ -2,8 +2,11 @@
 // the choice persists across reloads; turning semantic search back on resumes cleanly.
 import {
   test, expect, landingUI, typeQuery, snapshot, stableSnapshot, statusText, trackWorkers, trackConsole, sleep,
+  enableSemanticButton,
 } from './harness.mjs';
 
+test.use({ semanticSearch: true });
+
 const WEIGHTS = 'onnx/model_quantized.onnx';
 
 test.describe('item 3: cancel', () => {
@@ -19,6 +22,7 @@ test.describe('item 3: cancel', () => {
     let requestsAtCancel = 0;
     await test.step('"Keyword only" stops further model requests', async () => {
       await ui.host.getByRole('button', { name: /keyword only/i }).click();
+      expect(await page.evaluate(() => JSON.parse(localStorage.getItem('diffct-search')).semantic)).toBe('off');
       requestsAtCancel = hub.log.length;
       held.release(); // the request in flight may finish; nothing new may start
       await sleep(2000);
@@ -38,13 +42,14 @@ test.describe('item 3: cancel', () => {
       expect(hub.log.slice(requestsAtCancel).map((r) => r.url), 'model requests after reload').toEqual([]);
       expect(workers.length - workersBefore, 'model workers started after reload').toBe(0);
       expect((await stableSnapshot(ui.listbox)).length, 'keyword results').toBeGreaterThan(0);
-      await expect(ui.host.getByRole('button', { name: /semantic/i })).toBeVisible();
+      await expect(enableSemanticButton(ui.host)).toBeVisible();
     });
 
     await test.step('turning semantic search back on resumes cleanly', async () => {
       const errorsBefore = errors.length;
       const downloadsBefore = hub.downloads(WEIGHTS);
-      await ui.host.getByRole('button', { name: /semantic/i }).click();
+      await enableSemanticButton(ui.host).click();
+      await expect.poll(() => page.evaluate(() => JSON.parse(localStorage.getItem('diffct-search')).semantic)).toBe('on');
       await site.waitProbe('session', () => true, 30_000);
       await site.waitProbe('embed', (p) => p.text.endsWith('multi GPU'), 30_000);
       await stableSnapshot(ui.listbox);
@@ -78,9 +83,9 @@ test.describe('item 3: cancel', () => {
     await typeQuery(ui.input, 'fan beam');
     await held.seen;
     await ui.host.getByRole('button', { name: /keyword only/i }).click();
-    await expect(ui.host.getByRole('button', { name: /semantic/i })).toBeVisible();
+    await expect(enableSemanticButton(ui.host)).toBeVisible();
     hub.clear(); // later downloads go through at once
-    await ui.host.getByRole('button', { name: /semantic/i }).click();
+    await enableSemanticButton(ui.host).click();
     held.release();
     await site.waitProbe('embed', (p) => p.text.endsWith('fan beam'), 30_000);
     await stableSnapshot(ui.listbox);

{diffct-2.5.0 → diffct-2.5.1}/docs/search/tests/item4-leaks.spec.mjs

@@ -6,6 +6,8 @@ import {
   test, expect, dialogUI, typeQuery, clearQuery, stableSnapshot, cdpWithWorkers, trackWorkers, sleep,
 } from './harness.mjs';
 
+test.use({ semanticSearch: true });
+
 // Bounds fixed before the first run. Both measurements are taken in the same UI state
 // (dialog closed, input empty) after forced garbage collection.
 const HEAP_BOUND = 1024 * 1024; // bytes, page and worker each

{diffct-2.5.0 → diffct-2.5.1}/docs/search/tests/item5-errors.spec.mjs

@@ -5,6 +5,8 @@ import {
   trackWorkers, sleep,
 } from './harness.mjs';
 
+test.use({ semanticSearch: true });
+
 const WEIGHTS = 'onnx/model_quantized.onnx';
 const NEXT = 'cone beam geometry';
 

{diffct-2.5.0 → diffct-2.5.1}/docs/search/tests/item6-a11y.spec.mjs

@@ -4,6 +4,8 @@ import {
   test, expect, landingUI, dialogUI, searchPageUI, typeQuery, stableSnapshot, sleep,
 } from './harness.mjs';
 
+test.use({ semanticSearch: true });
+
 async function open(page, where) {
   if (where === 'landing') {
     await page.goto('/index.html');

{diffct-2.5.0 → diffct-2.5.1}/docs/search/tests/item7-security.spec.mjs

@@ -6,6 +6,8 @@ import {
   test, expect, landingUI, dialogUI, searchPageUI, typeQuery, stableSnapshot, sleep,
 } from './harness.mjs';
 
+test.use({ semanticSearch: true });
+
 const PAYLOADS = [
   '<img src=x onerror=alert(1)>',
   '<img src=x onerror="window.__xss=1">',

diffct-2.5.1/docs/search/tests/semantic-opt-in.spec.mjs

@@ -0,0 +1,88 @@
+// Semantic search requires consent on every search surface. Connection hints do not add
+// another consent state. These tests deliberately use fresh storage, without preference seeding.
+import {
+  test, expect, landingUI, dialogUI, searchPageUI, typeQuery, stableSnapshot,
+  enableSemanticButton, trackWorkers, sleep,
+} from './harness.mjs';
+
+async function openSearch(page, where, reload = false) {
+  if (reload) await page.reload();
+  else await page.goto(where === 'landing' ? '/index.html' : where === 'dialog' ? '/quickstart.html' : '/search.html');
+  if (where === 'dialog') {
+    await page.keyboard.press('ControlOrMeta+k');
+    const ui = dialogUI(page);
+    await expect(ui.dialog).toBeVisible();
+    return ui;
+  }
+  return where === 'landing' ? landingUI(page) : searchPageUI(page);
+}
+
+async function expectKeywordOnly(ui, site, hub, workers) {
+  expect((await stableSnapshot(ui.listbox)).length, 'keyword results').toBeGreaterThan(0);
+  await expect(enableSemanticButton(ui.host)).toBeVisible();
+  await expect(ui.host.getByRole('button', { name: 'Download', exact: true })).toHaveCount(0);
+  const lb = await ui.listbox.locator();
+  await expect(lb.getByText(/^(Semantic|Both)$/)).toHaveCount(0);
+  // Observe beyond the query debounce, including any delayed automatic model load.
+  await sleep(1500);
+  expect(hub.log, 'all Hub requests, including metadata probes').toEqual([]);
+  expect(site.probes('pipeline'), 'model load attempts').toEqual([]);
+  expect(site.probes('session'), 'model sessions').toEqual([]);
+  expect(site.probes('embed'), 'semantic queries').toEqual([]);
+  expect(workers, 'workers before consent').toEqual([]);
+}
+
+async function expectSemantic(ui) {
+  const lb = await ui.listbox.locator();
+  await expect(lb.getByText(/^(Semantic|Both)$/).first()).toBeVisible({ timeout: 30_000 });
+}
+
+for (const where of ['landing', 'dialog', 'page']) {
+  test(`fresh visitor: keyword results and zero model requests (${where})`, async ({ page, site, hub }) => {
+    const workers = trackWorkers(page);
+    const ui = await openSearch(page, where);
+    expect(await page.evaluate(() => localStorage.getItem('diffct-search'))).toBeNull();
+    await typeQuery(ui.input, 'fan beam');
+    await expectKeywordOnly(ui, site, hub, workers);
+    await typeQuery(ui.input, 'cone beam');
+    await expectKeywordOnly(ui, site, hub, workers);
+  });
+
+  test(`enable click merges the current query and persists across reload (${where})`, async ({ page, site, hub }) => {
+    const workers = trackWorkers(page);
+    let ui = await openSearch(page, where);
+    await typeQuery(ui.input, 'fan beam');
+    await expectKeywordOnly(ui, site, hub, workers);
+    await enableSemanticButton(ui.host).click();
+    await expect.poll(() => page.evaluate(() => JSON.parse(localStorage.getItem('diffct-search')))).toMatchObject({ semantic: 'on' });
+    await site.waitProbe('embed', (p) => p.text.endsWith('fan beam'));
+    await expectSemantic(ui);
+    await expect(ui.input).toHaveValue('fan beam');
+    expect(hub.downloads('onnx/model_quantized.onnx')).toBe(1);
+    expect(workers.length, 'model loads in one Web Worker').toBe(1);
+    expect(site.probes('session').length).toBe(1);
+
+    ui = await openSearch(page, where, true);
+    await typeQuery(ui.input, 'curved detector');
+    await site.waitProbe('embed', (p) => p.text.endsWith('curved detector'));
+    await expectSemantic(ui);
+    expect(site.probes('session').length, 'reload automatically loads a new session').toBe(2);
+    expect(await page.evaluate(() => JSON.parse(localStorage.getItem('diffct-search')).semantic)).toBe('on');
+  });
+}
+
+for (const connection of [{ saveData: true, type: 'wifi' }, { saveData: false, type: 'cellular' }]) {
+  test(`connection ${JSON.stringify(connection)} uses the same enable button without Download consent`, async ({ page, site, hub }) => {
+    await page.addInitScript((value) => {
+      Object.defineProperty(navigator, 'connection', { configurable: true, value });
+    }, connection);
+    const workers = trackWorkers(page);
+    const ui = await openSearch(page, 'landing');
+    await typeQuery(ui.input, 'fan beam');
+    await expectKeywordOnly(ui, site, hub, workers);
+    await enableSemanticButton(ui.host).click();
+    await site.waitProbe('embed', (p) => p.text.endsWith('fan beam'));
+    await expectSemantic(ui);
+    await expect(ui.host.getByRole('button', { name: 'Download', exact: true })).toHaveCount(0);
+  });
+}

{diffct-2.5.0 → diffct-2.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "diffct"
-version = "2.5.0"
+version = "2.5.1"
 description = "Differentiable CT projection and reconstruction: precision modes, streaming, distributed execution and geometry gradients"
 readme = "README.md"
 requires-python = ">=3.10"