---
title: "2026-09-18 NanoVirDx thin DiffSim adapter review"
description: "Investigated DiffSim 0.1.100, upgraded NanoVirDx, and identified the package and output boundaries for a thin adapter."
image: "https://docs.virdx.dev/img/virdx-social-card.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.virdx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 2026-09-18 NanoVirDx thin DiffSim adapter review

## Work Done

- Compared NanoVirDx's 503-line DiffSim wrapper with the breaking DiffSim sequence rewrite released in `0.1.99` and republished with relaxed dependencies as `0.1.100`.
- Confirmed that `SimCfg`, `run_simulation`, `TissueCharacteristics`, and the old idealised sequence types were removed. The replacement public surface includes `domain_from_histo`, `Tissues`, `Scanner`, `SimState.with_walkers_sampled`, packed sequences, `simulate`, and US-spelled idealized sequence types.
- Found that the repository's `apps/gen4ve2e` runner owns output persistence and postprocessing but is not included in the installed DiffSim package. The package itself does not write NIfTIs, derive ADC, or expose a high-level result contract.
- Opened DiffSim PR [#738](https://github.com/virdx/diffsim/pull/738) to relax `virdx-ome` to `>=0.0.19,<0.1`. The resulting `0.1.100` package resolved successfully with Histo and `virdx-ome 0.0.24`.
- Ran `pixi upgrade diffsim` in NanoVirDx, installed and imported DiffSim `0.1.100`, verified `domain_from_histo` and `simulate`, lock-checked the environment, then committed and pushed `c0e41b83` to `origin/fk/nanovirdx`.
- Replaced the 503-line NanoVirDx wrapper with a 195-line adapter using the `0.1.100` public APIs. DiffSim now owns domain loading, tissue construction, walker sampling, sequence packing, simulation, and magnetization capture. NanoVirDx retains only protocol constants, NIfTI persistence, and ADC derivation so `BPMRIBatch` remains unchanged.
- Removed local cache manifests, retry/downsampling fallback, duplicate metadata, state cache, segmentation loading, device validation, noise/smoothing, and foreground-mask persistence. Removed the now-unused direct SciPy dependency.
- Validated a complete synthetic 13-class Histo-domain simulation on Metal with T2, high-b DWI, and finite ADC NIfTIs, then committed and pushed `39aa23a5` to `origin/fk/nanovirdx`.

## Lessons Learned: Pitfalls

- DiffSim `0.1.99` was a large breaking API rewrite under a patch version and originally constrained `virdx-ome` to the incompatible `0.0.19` patch series.
- The earlier recommendation to simplify through `SimCfg.run()` was stale: `SimCfg` was removed in `0.1.99`.
- The current `BPMRIBatch` contract requires derived ADC, while DiffSim's native/reference outputs do not include ADC. Preserving that contract keeps a small ADC calculation in NanoVirDx.
- The reference `gen4ve2e` app targets the current 13-class Histo domain schema. An older 40-class fixture with grade labels encoded at 128-139 cannot pass DiffSim `domain_from_histo`'s mapping-length contract and is not supported by the simplified adapter.
- The simplified outputs are native magnitude T2/high-b images plus derived ADC. The prior wrapper's synthetic smoothing/noise and explicit foreground-mask files were removed rather than duplicated outside DiffSim.
- The high-level `gen4ve2e` implementation looks reusable but is application code outside the built wheel, so NanoVirDx cannot delegate to it through the packaged dependency.

## Lessons Learned: Improvements

- Promote a stable high-level generation runner and result type from `apps/gen4ve2e` into `src/diffsim` before reducing NanoVirDx to a Histo-style thin adapter.
- If native DiffSim output becomes a reusable product boundary, introduce `DiffsimOutputBatch` and move ADC derivation into a separate transformer. For now, the small ADC calculation preserves `BPMRIBatch` without a public output change.
- Treat package release notes or compatibility declarations as necessary for breaking internal API changes even before semantic version `1.0`.

Source: https://docs.virdx.dev/knowledge/inbox/2026-09-18-diffsim-nanovirdx-thin-adapter-review/index.mdx