feat(diffusion): schedulers + integrate into diffusion model (Part of #261, Fixes #263)

[ooples]

Broadened scope per discussion: this PR now contributes to #261 (Introduce Diffusion Models – Part 1) by providing generic schedulers and will add the first diffusion model with constructor-injected scheduler.

• Refactor: generic IStepScheduler<T>, SchedulerConfig<T>, split enums per file; use Vector<T> and INumericOperations<T>
• Next in this PR: add IDiffusionModel<T> and a minimal DDPMModel<T> integrating the scheduler (constructor-injected) with tests
• Note: Umbrella/acceptance criteria updated in #261; schedulers library remains tracked in #263

[coderabbitai[bot]]

[!NOTE]

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Summary by CodeRabbit

• New Features
  • Added diffusion model framework enabling image generation and iterative denoising workflows
  • Introduced multiple scheduler implementations for flexible model behavior during inference
  • Enabled model serialization, state persistence, checkpoint management, and reproducible runs
  • Added gradient computation and loss-based training capabilities
  • Included feature importance tracking and model cloning functionality

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Walkthrough

Adds scheduler infrastructure (StepSchedulerBase, SchedulerConfig), two schedulers (DDIM, PNDM), a DiffusionModelBase with generation/training/serialization APIs, a DDPMModel scaffold, diffusion options, unit tests for schedulers/models, and CI workflow trigger adjustments.

Changes

Cohort / File(s)	Summary
Core diffusion base src/Diffusion/DiffusionModelBase.cs	Adds DiffusionModelBase<T> with scheduler integration, generation loop, abstract PredictNoise, training/prediction APIs, serialization/checkpointing, parameter and feature management, gradient helpers, and noise sampling.
Concrete model (scaffold) src/Diffusion/DDPMModel.cs	Adds DDPMModel<T> implementing placeholder noise predictor, parameter storage, PredictNoise, Get/SetParameters, Clone/DeepCopy and factory creation.
Scheduler base & utilities src/Diffusion/Schedulers/StepSchedulerBase.cs	Adds StepSchedulerBase<T> with beta schedule initialization (Linear/ScaledLinear/SquaredCosine), alpha computations, timestep management, AddNoise/GetAlphaCumulativeProduct helpers, state persistence, validation and clipping helpers.
Scheduler config src/Diffusion/Schedulers/SchedulerConfig.cs	Adds SchedulerConfig<T> exposing TrainTimesteps, BetaStart, BetaEnd, BetaSchedule, ClipSample, PredictionType with constructor validation (trainTimesteps > 1).
DDIM scheduler src/Diffusion/Schedulers/DDIMScheduler.cs	Adds sealed DDIMScheduler<T> implementing DDIM step: input validation, x0 prediction from model epsilon, optional clipping, sigma computation from eta, coefficient derivation, stability guards and optional noise handling to produce previous sample.
PNDM scheduler src/Diffusion/Schedulers/PNDMScheduler.cs	Adds PNDMScheduler<T> implementing PRK warmup and PLMS multi-step phases, internal ets history and counter, SetTimesteps, StepPrk/StepPlms, multi-step coefficient computation and state save/load.
Options src/Models/Options/DiffusionModelOptions.cs	Adds DiffusionModelOptions<T> with defaults for learning rate, timesteps, beta schedule, prediction type, clipping, inference steps, and optional loss function.
Unit tests tests/AiDotNet.Tests/UnitTests/Diffusion/Schedulers/PNDMSchedulerTests.cs, tests/UnitTests/Models/Generative/Diffusion/DDPMModelTests.cs	Adds tests for PNDMScheduler behavior, state save/load, PRK→PLMS transitions, and a DDPMModel test using a NoopScheduler to validate scheduler integration and tensor shapes.
CI workflows .github/workflows/commitlint.yml, .github/workflows/build.yml, .github/workflows/codeql.yml	Removes explicit commitlint configFile arg, widens build/codeql triggers (removes path filters), and adds workflow_dispatch to CodeQL.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant Client
    participant Model as DiffusionModelBase<T>
    participant Scheduler as IStepScheduler<T>
    participant RNG as Random/Noise

    Client->>Model: Generate(shape, steps, seed?)
    Model->>RNG: Seed RNG (optional)
    Model->>Scheduler: SetTimesteps(numInferenceSteps)
    loop each timestep t (descending)
        Model->>Model: PredictNoise(noisySample, t)
        Model->>Scheduler: Step(modelOutput, t, sample, eta, noise?)
        alt Scheduler needs stochastic noise (eta>0)
            Scheduler->>RNG: Request/sample noise
        end
        Scheduler-->>Model: previous sample x_{t-1}
        Model->>Model: update sample = x_{t-1}
    end
    Model-->>Client: return generated sample

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

• Areas needing extra attention:
  • src/Diffusion/Schedulers/DDIMScheduler.cs — x0 derivation, sigma/eta math, sqrt and clipping stability.
  • src/Diffusion/Schedulers/StepSchedulerBase.cs — beta schedule formulas and alpha cumulative product correctness.
  • src/Diffusion/Schedulers/PNDMScheduler.cs — PRK→PLMS transition, ets history management and coefficient math.
  • src/Diffusion/DiffusionModelBase.cs — generation loop correctness, state serialization format and scheduler persistence.
  • Generic numeric abstraction (INumericOperations<T>) usage across schedulers/models for type-safety and edge cases.

Possibly related issues

• ooples/AiDotNet#263 — Implements DDIM and PNDM schedulers and scheduler config types referenced by the issue.
• ooples/AiDotNet#261 — Implements core diffusion model and scheduler components (DDPMModel, schedulers, StepSchedulerBase) that align with the issue objectives.

Poem

🐇
I hopped through timesteps, soft and keen,
I nudged the noise until the scene,
With tiny clips and sigma bright,
I step, I calm — the pixels light,
A furred delight in code unseen. 🎨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 54.62% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding diffusion schedulers and integrating them into the diffusion model, with clear issue references.
Description check	✅ Passed	The description is directly related to the changeset, explaining the refactoring of generic schedulers, their integration with diffusion models, and the scope contribution to issue #261.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment
• [ ] Commit unit tests in branch feature/issue-263-diffusion-schedulers-library-ddim-pndm-dpm-solver

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[ooples]

Update: Refactored to align with project rules — made scheduler generic on T with INumericOperations<T>, replaced arrays with Vector<T>, split enums/config into separate files, kept .NET 4.6.2 compatibility, and tests updated accordingly. Will integrate with PredictionModelBuilder where appropriate in follow-ups (if needed for orchestration).