SCIOVANTA

Dissolution / comparison kit

Compare with DDSolver

Use the same measured observations and compare the actual exported outputs with the existing deterministic harness.

  1. Export the same observations

    Keep units, fitting windows and model definitions identical. This page does not supply or impersonate a DDSolver result.

  2. Normalize the actual DDSolver export

    Use the documented CSV/Excel conversion script in the kit. Missing and ambiguous columns must be resolved explicitly.

  3. Compare parameters and delta-AIC

    The suite uses N ln(SSE/N)+2p; DDSolver uses N ln(SSE)+2p. The existing cohort logic compares delta-AIC, not these absolute AIC values.

Download comparison kit
Existing comparison-kit instructions (unchanged)
# Owner-run commercial software comparison

Status: NOT RUN. DDSolver and Design-Expert were not available or executed.
Suite outputs in suite-expected.json are generated by the deterministic engine;
they are NOT external results. Do not copy them into the external result template.

1. Retain a copy of the original benchmark CSVs and settings.json. Record the
   software version, operating system, date and all calculation options.
2. In DDSolver, import the time column (hours) and F1 column (percentage release)
   of each first-order, zero-order and Higuchi CSV. Use the corresponding model
   specified in settings.json; exclude zero for fitting, use unweighted nonlinear
   least squares on the original percentage scale, no lag or intercept, maximum
   release fixed at 100 for first-order. Fit k, record k and R² without rounding.
   Compute DE and MDT on the full observed interval including the zero point.
   Check the program's exact definition against METHODS/VALIDATION before comparing.
   Menu names depend on the installed DDSolver/Excel version; record any unavailable option.
3. In Design-Expert, import each DoE CSV as a user-defined design with two continuous
   numeric factors. Use the factor units and low/high settings in settings.json.
   Fit the full quadratic (intercept, A, B, AB, A², B²), no transformation or term
   removal. Record coded coefficients in that order. For optimization, keep both
   factors in [-1,+1] coded bounds, maximize response with desirability low=0,
   high=100. Record coded candidate and desirability. Multiple equally optimal
   candidates may require a documented interpretation; never alter tolerances to pass.
4. These noiseless synthetic cases test arithmetic only. They do not establish
   inferential validity or software equivalence for experimental data.
5. Copy external-results-BLANK.csv to external-results.csv. Paste only values
   actually obtained from the programs into external_value and identify program
   and program_version. Leave unavailable values blank.
6. Run `python comparison-kit/compare.py comparison-kit/external-results.csv`.
   PASS requires |difference| <= 1e-6 + 1e-6*|Suite value|. Missing values are NOT RUN.
   Exit codes: 0 complete pass, 1 mismatch, 2 incomplete. Archive exports/screenshots,
   settings and the comparison output. Investigate mismatches before research use.

The instruction sheet describes required settings, not a claim that every version
uses those defaults. No regulatory acceptance or commercial-program agreement is claimed.

The audit's supplied studentized-range prototype and benchmark are preserved as
received in `audit-prototype/`. The original benchmark references its author's
local prototype module name. Executable Suite comparisons are
`tests/quadrature_equivalence.py`, `tests/games_howell_lanes.py`, and
`tests/games_howell_compare.py`; these print the required Node/Python versions.
They do not substitute for external DDSolver or Design-Expert comparisons.

## DDSolver model tables: six models, delta-AIC and ranking

No DDSolver execution is supplied. Blank templates contain no external scientific
results. Never fill them with our values and claim an external comparison.
Version stays **0.2.0**; use Node **24.19.0**, Python **3.12.14** and
`python -m pip install -r requirements-dev.txt`.

1. Preserve original observations and the unedited DDSolver export. Record the
   DDSolver/Excel versions, date, time unit, response scale, model variant,
   bounds, weighting and every selected observation. Do not round exported values.
2. Generate our mean-profile fits from the same request:
   ```sh
   node comparison-kit/export_models.mjs comparison-kit/ddsolver-request.json comparison-kit/suite-models.csv
   ```
   The CSV schema remains exactly:
   `dataset,model,k,n,R2adj,AIC,SSE,N,p,selection,program_version`.
   A companion `.csv.diagnostics.json` records R² alternatives and a CSV SHA-256;
   keep it beside the CSV. A stale sidecar is rejected.
3. Fit the same mean percentages and times in DDSolver, using unweighted nonlinear
   least squares on the original response scale, no intercept/lag, and the same
   bounds. The engine excludes t=0 and limits KP to <=60% by default. Compare
   only identical selections and response data. These are required settings,
   not assertions about DDSolver defaults.

| ID | Equation | CSV k | CSV n | p |
| --- | --- | --- | --- | --- |
| zero | Q=k*t | k | blank | 1 |
| first | Q=100*(1-exp(-k*t)) | k | blank | 1 |
| higuchi | Q=k*sqrt(t) | k | blank | 1 |
| kp | Q=k*t^n | k | exponent n | 2 |
| weibull | Q=100*(1-exp(-t^beta/alpha)) | alpha | beta | 2 |
| hixson | Q=100*(1-(1-k*t)^3) | kHC | blank | 1 |

For Weibull use **Weibull_2**, fixed maximum 100 and no lag. Alpha has units
`time^beta`; it is not the characteristic time `td=alpha^(1/beta)`. Do not paste
td into k. Hixson kHC has units `1/time`; a cube-root-percent coefficient uses a
different scale and must not be silently substituted. The comparison output
prints parameter labels. This export covers mean fits, not replicate fits.

4. Copy `ddsolver-export-BLANK.csv` and insert actual external values. For the
   noisy case use `synthetic-noisy-ddsolver-BLANK.csv`. N is observation count;
   p is fitted parameter count; selection is the pipe-separated list of fitted
   times in engine order. Verify these independently against the actual fit.
   Operator-entered metadata must not be represented as program-generated output.
5. Normalize a flat DDSolver table if needed:
   ```sh
   python scripts/ddsolver_to_csv.py actual-export.csv comparison-kit/ddsolver-export.csv
   python scripts/ddsolver_to_csv.py actual-export.xlsx comparison-kit/ddsolver-export.csv --sheet Models
   ```
   Supported inputs: UTF-8 comma-separated CSV or XLSX, header in row 1, one model
   per row. Legacy XLS must first be saved as XLSX or UTF-8 CSV in Excel or
   LibreOffice. Preserve the original file. Arbitrary native report layouts are
   not automatically inferred: arrange an explicitly selected table with the
   documented columns, retaining traceability to the original cells.

| Canonical header | Accepted aliases (case-sensitive) |
| --- | --- |
| dataset | Dataset, Profile |
| model | Model |
| k | Rate constant, alpha, Alpha |
| n | Exponent, beta, Beta |
| R2adj | Adjusted R2, Adjusted R², R2 adjusted |
| AIC | AIC |
| SSE | SSE |
| N | Observations |
| p | Parameters |
| selection | Fitted times |
| program_version | DDSolver version |

All columns are required even when a scientific value is unavailable/blank.
`n` and `N` are deliberately case-sensitive. Model names may use the IDs above,
Zero-order, First-order, Higuchi, Korsmeyer-Peppas, Weibull_2 or Hixson-Crowell
(typographic en dashes also accepted for KP and Hixson). A column headed Alpha
maps to k only under the documented Weibull convention; put mixed model
parameters into the canonical k/n columns yourself. Duplicate aliases, missing
or unknown headers, unsupported model variants, wrong parameter counts, merged
cells, formulas, NaN, wrong selection lengths and ambiguous worksheets fail.
Formula cells must be pasted as actual values first. No numeric values, units,
metadata or AIC conversions are invented by the converter. Invalid input leaves
an existing destination untouched. A selected sheet can be specified by name;
otherwise the workbook must contain exactly one sheet.

6. Compare:
   ```sh
   python comparison-kit/compare_ddsolver.py comparison-kit/suite-models.csv comparison-kit/ddsolver-export.csv --output comparison-kit/ddsolver-differences.csv
   ```
   Output includes raw metrics, absolute/relative differences, both delta-AIC
   values and model ranks. Relative error is `abs(ours-external)/abs(external)`;
   it is blank for a nonzero difference against zero. Existing pass/fail tolerance
   stays `1e-6 + 1e-6*abs(ours)`; frozen-engine tolerance remains absolute 1e-9.
7. AIC conventions remain Suite `N*ln(SSE/N)+2*p`, DDSolver `N*ln(SSE)+2*p`.
   Each input is checked against its own formula. **Compare delta-AIC, never
   absolute AIC across definitions.** The offset for equal SSE is `N*ln(N)`.
   Cohorts require identical dataset, N and selection. A shorter KP selection
   forms its own cohort; a one-model rank says nothing about competitors.
   Missing/undefined AIC withholds the entire cohort ranking. SSE=0 has no finite
   AIC here. Ties share rank (1,1,3); near-tie rank reversals are reported.
8. Exit 0 = complete numerical pass, 1 = mismatch, 2 = incomplete/NOT RUN.
   Schema/metadata errors fail loudly. A pass does not validate other datasets.

### Adjusted R²: two explicit definitions

The **unchanged pass/fail** value is the engine's centered definition, even for
models without an intercept:
`SSTc=sum((y-mean(y))^2); R2=1-SSE/SSTc; R2adj=1-((1-R2)*(N-1))/(N-p)`.
This is algebraically `1-[SSE/(N-p)]/[SSTc/(N-1)]`.

The sidecar computes an **uncentered alternative, diagnostic only**:
`1-[SSE/(N-p)]/[sum(y^2)/N]`, using exactly the fitted observations.
Both are printed and included side by side in the comparison output. p counts
all fitted parameters. Undefined denominators yield no value. The alternative
never affects tolerance, status or ranking. Without a sidecar the alternative
is explicitly unavailable. Do not assume DDSolver uses either definition in a
particular version: retain its reported adjusted R² and inspect its documented
formula when a mismatch occurs. No alternate definition is substituted to pass.

### Synthetic noisy ranking example

`synthetic-noisy.csv` is synthetic, not experimental data or a DDSolver export.
Its generator uses LCG seed 20261011, Weibull-like profiles plus small uniform
noise, minutes and percentage release. Regenerate deterministically:

```sh
node comparison-kit/build_noisy_example.mjs
node comparison-kit/export_models.mjs comparison-kit/synthetic-noisy-request.json comparison-kit/synthetic-noisy-suite-models.csv
python -m pytest tests/test_ddsolver_harness.py tests/test_comparison_upgrade.py -q
```

The test requires at least three finite-AIC models with N>=6 per full-profile
cohort, exercises every exported model through the existing cohort/ranking
logic, and verifies that a deliberately perturbed synthetic external table
fails. The temporary algebraic table is labeled `SYNTHETIC ... NOT DDSolver`;
this is a harness test, not independent commercial-software agreement.

### f1, f2, DE and MDT comparison

The published DDSolver paper documents f1/f2 modules and DD_f1/DD_f2 functions,
plus DD_DE and DD_MDT functions. Thus none of these four scalars is categorically
unavailable in DDSolver. Actual availability/export layout in the owner's
installed version is **unverified here**. Source: Zhang et al. (2010),
https://pmc.ncbi.nlm.nih.gov/articles/PMC2895453/ (Tables II–IV).

**Not supplied as DDSolver outputs by this kit:** the explicit `gt`/`ge` selector,
retained-time audit metadata, our uncentered adjusted-R² diagnostic, and any
actual external result. Record selection/rule metadata manually from the
verified calculation; these are not claimed to be native DDSolver export fields.
If a scalar or matching option cannot be obtained, leave its value blank and
record the unavailable feature/version in the comparison notes; status is NOT RUN.
Do not substitute a Suite-computed value for an unavailable DDSolver result.

1. Export our deterministic values and a separate blank template:
   ```sh
   node comparison-kit/export_profile_metrics.mjs comparison-kit/synthetic-noisy-request.json comparison-kit/suite-profile-metrics.csv comparison-kit/ddsolver-profile-metrics-BLANK.csv
   ```
2. For f1/f2, exclude t=0 and retain observations through the first time **both**
   mean profiles are strictly >85%, inclusive. Exactly 85% does not trigger this
   default `truncate:gt` rule. `truncate:ge` is separately labelled and must match
   on both sides. Feed precisely that selected pair of mean profiles into the
   DDSolver function; record the selection instead of assuming its defaults.
   f1 is `100*sum(abs(R-T))/sum(R)`; f2 is
   `50*log10(100/sqrt(1+mean((R-T)^2)))`. These examples have one profile per product
   and are exploratory, not an applicability or regulatory finding.
3. For DE/MDT use every observed point, including (0,0), without extrapolation.
   DE (%) is trapezoidal area divided by observed duration (percentage responses).
   MDT is `sum(midpoint_time*release_increment)/sum(release_increment)` in the
   selected time unit. Negative increments withhold MDT. DDSolver settings must
   match the same interval, normalization and release convention. These are
   observed-interval metrics, not a claim of release completion at infinity.
4. Copy `ddsolver-profile-metrics-BLANK.csv` to an external result file. Fill only
   actual values and the actual program version. Keep columns exactly
   `case,metric,value,selection,threshold_rule,time_unit,program_version`.
5. Run:
   ```sh
   python comparison-kit/compare_profile_metrics.py comparison-kit/suite-profile-metrics.csv comparison-kit/ddsolver-profile-metrics.csv --output comparison-kit/profile-differences.csv
   ```
   The existing `1e-6 + 1e-6*abs(ours)` rule and exit codes apply. Different units,
   time selections or 85% rules are rejected. Blank or undefined values do not
   constitute a complete pass. Our numeric values are in the generated CSV;
   the blank-template run intentionally exits 2.