Time

mujou.time

The time of mujou.

Every run measures its nodes' dt on one timer, a time axis that can be scaled and paused. By default every run shares global_timer; give a run a Timer of its own with mujou.run(..., timer=...). The host controls the time of a run through run.timer, and a node reads it with self.timer.

• Timer: a time axis, running with the real clock at a scale
• VirtualTimer: a Timer that moves only when advanced, for tests
• ReadOnlyTimer: the reading side of a timer, as a node sees its run's timer (Node.timer)
• Timestamp: a time on a timer, as Run.read_with_time and Port.recv_with_time give it
• global_timer: the timer of every run not given one of its own

Durations are in seconds of the timer (sleep, advance, dt, period), except timeouts, which are in real seconds. Only the host controls the time: sleep, pause, resume, set_time_scale and VirtualTimer.advance raise RuntimeError in a node's hook.

global_timer module-attribute

global_timer: Final[Timer] = Timer(now=Timestamp(ns=2067550236))

A time axis that a run's nodes measure their dt on.

Timer() starts at start and runs with the real clock, time_scale seconds of the timer per real second. Give it to mujou.run(..., timer=...) to run a network on a time of its own: a pause of that run (as Run.state_dict takes) then stops only this timer, not global_timer, which every other run uses by default. Every time of the run is a Timestamp on it.

Only the host controls a timer: sleep, pause, resume, set_time_scale (and VirtualTimer.advance) raise RuntimeError in a node's hook, where a node would wait for, or change the dt of, the other nodes. A node reads the time of its run with self.timer.

pause stops the time of every run on the timer at one time T until resume. Take the states of several runs on one timer while it is paused, so that all of them are of the same time T.

The time is held in nanoseconds and saturates at about 584 years.

RAISES	DESCRIPTION
ValueError	time_scale is not finite and > 0.

Timer

A time axis that a run's nodes measure their dt on.

Timer() starts at start and runs with the real clock, time_scale seconds of the timer per real second. Give it to mujou.run(..., timer=...) to run a network on a time of its own: a pause of that run (as Run.state_dict takes) then stops only this timer, not global_timer, which every other run uses by default. Every time of the run is a Timestamp on it.

Only the host controls a timer: sleep, pause, resume, set_time_scale (and VirtualTimer.advance) raise RuntimeError in a node's hook, where a node would wait for, or change the dt of, the other nodes. A node reads the time of its run with self.timer.

pause stops the time of every run on the timer at one time T until resume. Take the states of several runs on one timer while it is paused, so that all of them are of the same time T.

The time is held in nanoseconds and saturates at about 584 years.

RAISES	DESCRIPTION
ValueError	time_scale is not finite and > 0.

is_paused

is_paused() -> bool

Whether the time is stopped, by pause or by a run on this timer that is starting or taking its state. The clock of a VirtualTimer standing still does not count as paused.

now

now() -> Timestamp

The time now.

pause

pause() -> None

Stops the time until resume.

While paused, the nodes of the runs on this timer do not update (the first dt after resume does not count the pause), and sleep does not return until resumed. Run.state_dict still works. This is a switch, not a count: pausing twice needs one resume. A run that takes its state holds the time paused on its own, apart from this switch, so resume does not end that, and its end does not end this pause.

RAISES	DESCRIPTION
RuntimeError	This is called from a node's hook.

resume

resume() -> None

Turns off the switch of pause: the time moves again from where it stopped, unless a run on this timer is taking its state.

RAISES	DESCRIPTION
RuntimeError	This is called from a node's hook.

set_time_scale

set_time_scale(scale: SupportsFloat | SupportsIndex) -> None

Sets how many seconds of this timer pass per real second.

RAISES	DESCRIPTION
ValueError	scale is not finite and > 0. Use pause to stop the time.
RuntimeError	This is called from a node's hook.

sleep

sleep(seconds: SupportsFloat | SupportsIndex) -> None

Blocks for seconds of this timer's time, following the scale and the pauses: while paused, it does not return until resumed. Waits without the GIL and checks for signals (Ctrl-C) in between.

RAISES	DESCRIPTION
ValueError	seconds is negative or not finite.
RuntimeError	This is called from a node's hook.

time_scale

time_scale() -> float

How many seconds of this timer pass per real second.

VirtualTimer

Bases: Timer

A timer for tests: its time moves only when advance moves it.

It starts at start. Its time scale does not apply to advance; it is kept as a Timer keeps it (time_scale() and the state of a run on it). mujou.testing.run runs a network on a new one unless given one, and ManualRun.step(dt) advances it.

RAISES	DESCRIPTION
ValueError	time_scale is not finite and > 0.

is_paused

is_paused() -> bool

Whether the time is stopped, by pause or by a run on this timer that is starting or taking its state. The clock of a VirtualTimer standing still does not count as paused.

now

now() -> Timestamp

The time now.

pause

pause() -> None

Stops the time until resume.

While paused, the nodes of the runs on this timer do not update (the first dt after resume does not count the pause), and sleep does not return until resumed. Run.state_dict still works. This is a switch, not a count: pausing twice needs one resume. A run that takes its state holds the time paused on its own, apart from this switch, so resume does not end that, and its end does not end this pause.

RAISES	DESCRIPTION
RuntimeError	This is called from a node's hook.

resume

resume() -> None

Turns off the switch of pause: the time moves again from where it stopped, unless a run on this timer is taking its state.

RAISES	DESCRIPTION
RuntimeError	This is called from a node's hook.

set_time_scale

set_time_scale(scale: SupportsFloat | SupportsIndex) -> None

Sets how many seconds of this timer pass per real second.

RAISES	DESCRIPTION
ValueError	scale is not finite and > 0. Use pause to stop the time.
RuntimeError	This is called from a node's hook.

sleep

sleep(seconds: SupportsFloat | SupportsIndex) -> None

Blocks for seconds of this timer's time, following the scale and the pauses: while paused, it does not return until resumed. Waits without the GIL and checks for signals (Ctrl-C) in between.

RAISES	DESCRIPTION
ValueError	seconds is negative or not finite.
RuntimeError	This is called from a node's hook.

time_scale

time_scale() -> float

How many seconds of this timer pass per real second.

advance

advance(seconds: SupportsFloat | SupportsIndex) -> None

Moves the time forward by seconds, at once.

RAISES	DESCRIPTION
ValueError	seconds is negative or not finite.
RuntimeError	The timer is paused (by pause, or by a run on it that is starting or taking its state), or this is called from a node's hook.

ReadOnlyTimer

The reading side of a timer: its time and its scale, and nothing that changes them. What a node sees of its run's timer as Node.timer.

ReadOnlyTimer(timer) reads timer. The one a run gives its nodes stops at the time the run ends: every time of the run is at most that time.

now

now() -> Timestamp

The time now.

time_scale

time_scale() -> float

How many seconds of the timer pass per real second.

Timestamp

A time on a timer.

float(ts) is the time in seconds; ts.ns is the exact time in nanoseconds. Timestamps compare and hash by time, so compare only those of one timer: a timestamp does not say which timer it is on. a - b is the time from b to a in seconds, a float that is negative when b is later. Timestamps pickle and copy.

ns property

ns: int

The time in nanoseconds.