snnlab.sim.timing
Complete declared API of the timing module, with signatures, data fields, validation and source.
Physical-time conversion shared by simulation entry points.
Trial durations use whole steps rounded downward, except for floating-point representations of an integer ratio. Refractory conversion declares whether physical durations must be exact or may use the nearest positive step count.
The signatures, defaults, fields, docstrings and implementation excerpts below are generated from the Python source. Annotations are shown as declared; unannotated means the source supplies no type annotation. These pages document callable surfaces, including legacy support utilities, without promising backend support for every declaration.
| Symbol | Kind |
|---|---|
| duration_steps | function |
| refractory_steps | function |
| duration_metadata | function |
| refractory_metadata | function |
duration_steps
def duration_steps(duration_ms: float, dt_ms: float) -> intSource docstring:
Return the number of complete steps, correcting near-integer roundoff.| Parameter | Annotation | Default | Meaning |
|---|---|---|---|
duration_ms | float | required | Physical presentation duration in milliseconds. |
dt_ms | float | required | Simulation timestep in milliseconds. |
Return annotation: int.
Return expressions (branch-dependent; names refer to the linked implementation):
nearest if _is_integer_ratio(ratio, nearest) else math.floor(ratio)Implementation
def duration_steps(duration_ms: float, dt_ms: float) -> int:
"""Return the number of complete steps, correcting near-integer roundoff."""
ratio = _step_ratio(duration_ms, dt_ms)
nearest = round(ratio)
return nearest if _is_integer_ratio(ratio, nearest) else math.floor(ratio)refractory_steps
def refractory_steps(duration_ms: float, dt_ms: float, *, policy: str='exact') -> intSource docstring:
Resolve a positive refractory duration using an explicit grid policy.| Parameter | Annotation | Default | Meaning |
|---|---|---|---|
duration_ms | float | required | Physical presentation duration in milliseconds. |
dt_ms | float | required | Simulation timestep in milliseconds. |
policy | str | 'exact' | Defined by the source contract and implementation below. |
Return annotation: int.
Return expressions (branch-dependent; names refer to the linked implementation):
max(1, nearest)nearestExplicit exceptions in this implementation; called helpers may raise additional errors:
| Explicit exception expression |
|---|
ValueError('refractory duration must be positive') |
ValueError("refractory policy must be 'exact' or 'nearest'") |
ValueError(f'refractory duration {duration_ms:g} ms is not a positive whole number of steps at dt={dt_ms:g} ms') |
Implementation
def refractory_steps(duration_ms: float, dt_ms: float, *, policy: str = "exact") -> int:
"""Resolve a positive refractory duration using an explicit grid policy."""
ratio = _step_ratio(duration_ms, dt_ms)
if duration_ms <= 0:
raise ValueError("refractory duration must be positive")
nearest = round(ratio)
if policy == "nearest":
return max(1, nearest)
if policy != "exact":
raise ValueError("refractory policy must be 'exact' or 'nearest'")
if nearest < 1 or not _is_integer_ratio(ratio, nearest):
raise ValueError(
f"refractory duration {duration_ms:g} ms is not a positive whole "
f"number of steps at dt={dt_ms:g} ms"
)
return nearestduration_metadata
def duration_metadata(duration_ms: float, dt_ms: float) -> dictSource docstring:
Record the requested trial duration and the duration actually integrated.| Parameter | Annotation | Default | Meaning |
|---|---|---|---|
duration_ms | float | required | Physical presentation duration in milliseconds. |
dt_ms | float | required | Simulation timestep in milliseconds. |
Return annotation: dict.
Return expressions (branch-dependent; names refer to the linked implementation):
{'nominal_duration_ms': float(duration_ms), 'duration_steps': steps, 'realized_duration_ms': steps * float(dt_ms)}Implementation
def duration_metadata(duration_ms: float, dt_ms: float) -> dict:
"""Record the requested trial duration and the duration actually integrated."""
steps = duration_steps(duration_ms, dt_ms)
return {
"nominal_duration_ms": float(duration_ms),
"duration_steps": steps,
"realized_duration_ms": steps * float(dt_ms),
}refractory_metadata
def refractory_metadata(refractory_e_ms: float, refractory_i_ms: float, dt_ms: float, *, policy: str='exact') -> dictSource docstring:
Record physical E/I durations and their validated runtime counters.| Parameter | Annotation | Default | Meaning |
|---|---|---|---|
refractory_e_ms | float | required | Defined by the source contract and implementation below. |
refractory_i_ms | float | required | Defined by the source contract and implementation below. |
dt_ms | float | required | Simulation timestep in milliseconds. |
policy | str | 'exact' | Defined by the source contract and implementation below. |
Return annotation: dict.
Return expressions (branch-dependent; names refer to the linked implementation):
{'refractory_e_ms': float(refractory_e_ms), 'refractory_i_ms': float(refractory_i_ms), 'refractory_policy': policy, 'refractory_e_steps': e_steps, 'refractory_i_steps': i_steps, 'realized_refractory_e_ms': e_steps * float(dt_ms), 'realized_refractory_i_ms': i_steps * float(dt_ms)}Implementation
def refractory_metadata(
refractory_e_ms: float,
refractory_i_ms: float,
dt_ms: float,
*,
policy: str = "exact",
) -> dict:
"""Record physical E/I durations and their validated runtime counters."""
e_steps = refractory_steps(refractory_e_ms, dt_ms, policy=policy)
i_steps = refractory_steps(refractory_i_ms, dt_ms, policy=policy)
return {
"refractory_e_ms": float(refractory_e_ms),
"refractory_i_ms": float(refractory_i_ms),
"refractory_policy": policy,
"refractory_e_steps": e_steps,
"refractory_i_steps": i_steps,
"realized_refractory_e_ms": e_steps * float(dt_ms),
"realized_refractory_i_ms": i_steps * float(dt_ms),
}