Document and optionally move train-envelope timing into Doric hardware sequencing

As of 2026-03-19, stimulation timing semantics need a clearer documented recommendation and a follow-up implementation decision.

Context

• The app currently uses Doric hardware for pulse shape (period_ms, time_on_ms) but still enforces the train envelope (train.on_seconds, train.off_seconds) in Python timers.
• Doric support clarified that the hardware-native mapping for a 20 Hz, 10 ms ON / 40 ms OFF pulse train with a 1 s ON / 3 s OFF envelope is:
  • period_ms = 50
  • time_on_ms = 10
  • nb_of_pulses_per_seq = 20
  • delay_between_seq_ms = 3000
  • nb_of_seq = 65535
• Doric also recommended validating sequence behavior in Doric Neuroscience Studio first, using the GUI signal preview before transferring settings into code via ttlModulation and related DLL/API parameters.

Why this matters

• Sequence semantics are not obvious, especially for nb_of_pulses_per_seq, delay_between_seq_ms, nb_of_seq, and Gated + Restart.
• Misunderstanding those fields can produce materially different stimulation behavior.
• If we want train envelopes to be hardware-timed, the controller should intentionally derive or honor those Doric sequence fields instead of relying on Python timers.

Current status

• Docs were updated locally to explain the timing split and to add a strong recommendation to validate waveform design in Doric Studio first.
• No runtime behavior was changed yet.

Follow-up questions

• Should stimulus.train.* remain an app-level abstraction only, with explicit stimulus.square.* overrides for hardware-native sequencing?
• Or should the controller derive Doric sequence parameters automatically from stimulus.pulse.* + stimulus.train.* when the pattern is representable in hardware?
• For closed-loop use, do we want hardware-native train envelopes by default, or only when a dedicated mode/flag is enabled?

Acceptance criteria

• Decide whether train OFF remains software-timed or moves to Doric-native sequencing.
• If moving to hardware, define the exact config contract and update stim_controller.py accordingly.
• Keep Doric Studio validation called out prominently in docs and operator workflow.

Start by validating the sequence behavior in Doric Neuroscience Studio using the GUI signal preview, then read stim_controller.py and the existing timing documentation. The work is done when the software-versus-hardware train-envelope decision is documented, the exact config contract is defined, and stim_controller.py is updated if hardware sequencing is chosen.