Viz

Visualize running simulations in Rerun.

`AgentsVisual(color_by=None, color_range=None, radius=None, *, position=None, path=None, recording=None)`

Bases: BaseVisual

Visual that logs the agents of a group as one batch per frame, colored by a state.

Agents on a grid or in a continuous space are logged as Points2D at their cell centres or positions, and agents on a network as GraphNodes at their nodes, which keep the pos attributes of the nodes, or the positions of a seeded spring layout of the network. On a grid the radius is in cells, and on a network a fraction of the spacing of neighbouring nodes. Without a given radius, agents in a continuous space take a share of the side of the space, smaller for larger groups. Agents in a continuous space are logged with their second coordinate negated, so the view, bounded by the space, draws them with the vertical axis up. Every point carries the agent id as a hidden label, so agents keep their identity across frames and removed agents disappear. Agents whose position is a state are logged at that state: positions of one coordinate, such as cars on a road, as one thin series of one color per agent under <path>/<position>, so their time series view, without a legend, is a space-time diagram, and positions of two coordinates as Points2D with the vertical axis up.

Parameters:

Name	Type	Description	Default
`color_by`	`str \| None`	The name of a numeric state that colors the agents, or `None` for one color.	`None`
`color_range`	`tuple[float, float] \| None`	The values at the two ends of the color scale, or `None` for a range widened to every logged value.	`None`
`radius`	`float \| None`	The radius of the points, or `None` for 0.4 on grids and networks and a share of the side of other spaces.	`None`
`position`	`str \| None`	The name of a state that holds the position of every agent, or `None` for the location in the space.	`None`
`path`	`str \| None`	The entity path of the element or agent group to draw, which also names it in the problem.	`None`
`recording`	`RecordingStream \| None`	The Rerun recording to log to, or `None` for the active recording of the thread.	`None`

Attributes:

Name	Type	Description
`styled_`		The entity paths whose series style is logged.
`span_`		The range of the colored values logged so far, or `None`.

Examples:

>>> from skcomplex.engine.viz import AgentsVisual
>>> AgentsVisual(color_by='opinion').color_by
'opinion'

Source code in src/skcomplex/engine/viz/_agents.py

def __init__(
    self,
    color_by: str | None = None,
    color_range: tuple[float, float] | None = None,
    radius: float | None = None,
    *,
    position: str | None = None,
    path: str | None = None,
    recording: rr.RecordingStream | None = None,
) -> None:
    self.color_by = color_by
    self.color_range = color_range
    self.radius = radius
    self.position = position
    self.path = path
    self.recording = recording

`AxisVisual(state, scalar=None, every=4, *, path=None, recording=None)`

Bases: BaseVisual

Visual that logs the axes of a tensor state or the arrows of a vector state at every sampled site of a lattice.

A tensor state logs one segment without head per sampled site along its principal axis, and a vector state one arrow per sampled site, under <path>/<state>/axes. A scalar state logs its image under <path>/<state>/image, so one view shows both. A site at the row and column of the lattice sits at the same pixel of the image.

Parameters:

Name	Type	Description	Default
`state`	`str`	The tensor or vector state to draw.	required
`scalar`	`str \| None`	The scalar state of the image, or `None` for no image.	`None`
`every`	`int`	The spacing of the sampled sites along every dimension.	`4`
`path`	`str \| None`	The entity path of the element to draw, which also names it in the problem.	`None`
`recording`	`RecordingStream \| None`	The Rerun recording to log to, or `None` for the active recording of the thread.	`None`

Attributes:

Name	Type	Description
`sites_`		The row and the column of every sampled site.

Raises:

Type	Description
`ValidationError`	The state is no tensor or vector state of a two-dimensional lattice, or the spacing is not positive.

Examples:

>>> from skcomplex.engine.viz import AxisVisual
>>> AxisVisual('Q', scalar='rho', every=2)
AxisVisual(every=2, scalar='rho', state='Q')

Source code in src/skcomplex/engine/viz/_axes.py

def __init__(
    self,
    state: str,
    scalar: str | None = None,
    every: int = 4,
    *,
    path: str | None = None,
    recording: rr.RecordingStream | None = None,
) -> None:
    super().__init__(path=path, recording=recording)
    self.state = state
    self.scalar = scalar
    self.every = every

`BaseVisual(*, path=None, recording=None)`

Bases: BaseConfig[BaseProblemSpec, FrameSpec]

Base class of visuals, which log the state of one element or agent group to a Rerun recording.

A visual follows the common API of the engine. prepare(problem) finds the element or agent group of the problem at the entity path path, forgets what earlier frames left, and sets the Rerun views that show what the visual logs. run(frame) logs the element at one frame to the recording recording: a compiled element through the hook _log, and agents through the hook _log_agents with the snapshot of the frame. Subclasses implement _log, _log_agents, or both, declare their views with _views, and are named by the kind of a VisualSpec. RerunObserver builds the visual of every element and agent group with their path and its recording.

Parameters:

Name	Type	Description	Default
`path`	`str \| None`	The entity path of the element or agent group to draw, which also names it in the problem.	`None`
`recording`	`RecordingStream \| None`	The Rerun recording to log to, or `None` for the active recording of the thread.	`None`

Attributes:

Name	Type	Description
`element_`		The compiled element or agents the visual logs.
`recording_`		The Rerun recording the visual logs to, or `None` while no recording is active.
`space_`		The space the agents of the problem live in, or `None`.
`layouts_`		The positions of the nodes of every network drawn so far, by the id of its graph.
`views_`		The Rerun views that show what the visual logs, each with an entity path of the element as origin.

Examples:

>>> from skcomplex.engine.compile import compile_system
>>> from skcomplex.engine.viz import ScalarsVisual
>>> from skcomplex.models import create
>>> problem = compile_system(create('lotka_volterra'))
>>> visual = ScalarsVisual(path='prey').check().prepare(problem)
>>> visual.element_.path, str(visual.views_[0].origin)
('prey', 'prey')

Source code in src/skcomplex/engine/viz/_base.py

def __init__(self, *, path: str | None = None, recording: rr.RecordingStream | None = None) -> None:
    self.path = path
    self.recording = recording

`prepare(problem=None)`

Prepare the checked visual for the element at its path in a compiled problem.

Parameters:

Name	Type	Description	Default
`problem`	`BaseProblemSpec \| None`	The compiled problem.	`None`

Returns:

Name	Type	Description
`self`	`Self`	The prepared visual, with its views `views_`.

Raises:

Type	Description
`ValidationError`	No element or agent group of the problem has the path of the visual.

Source code in src/skcomplex/engine/viz/_base.py

def prepare(self, problem: BaseProblemSpec | None = None) -> Self:
    """Prepare the checked visual for the element at its path in a compiled problem.

    Args:
        problem:
            The compiled problem.

    Returns:
        self:
            The prepared visual, with its views `views_`.

    Raises:
        ValidationError:
            No element or agent group of the problem has the path of the visual.
    """
    return super().prepare(problem)

`run(frame=None, final=False)`

Log the element or the agents of the visual at a frame.

Parameters:

Name	Type	Description	Default
`frame`	`FrameSpec \| None`	The frame.	`None`
`final`	`bool`	Whether this is the last call of the run.	`False`

Returns:

Name	Type	Description
`self`	`Self`	The visual.

Source code in src/skcomplex/engine/viz/_base.py

def run(self, frame: FrameSpec | None = None, final: bool = False) -> Self:
    """Log the element or the agents of the visual at a frame.

    Args:
        frame:
            The frame.

        final:
            Whether this is the last call of the run.

    Returns:
        self:
            The visual.
    """
    super().run(frame, final)
    return self

`BodiesVisual(positions, *, pivot=None, rods=False, traced=None, trail=_TRAIL_LENGTH, outline=(), marks=(), radius=None, path=None, recording=None)`

Bases: BaseVisual

Visual that draws bodies at positions computed from the states of an element, with rods, trails, and outlines.

The bodies are logged as points under <path>/bodies, the rods from the pivot through the bodies in order as one line strip under <path>/rods, the trails of the traced bodies as segments under <path>/trail that grow more transparent with age, the outlines once as static line strips under <path>/outline, and the marks once as static points under <path>/marks. Every state is also logged as a time series under <path>/<state>. Bodies with three coordinates are drawn in a 3D view. Bodies with two are drawn in a 2D view with the second coordinate negated, since Rerun's 2D views point their vertical axis down, so the views draw it upward.

Parameters:

Name	Type	Description	Default
`positions`	`Positions`	A function of the parameters and states of the element by keyword that returns one row `(x, y)` per body, or the names of the two states that hold the position of a single body.	required
`pivot`	`Sequence[float] \| None`	The fixed point the rods start from, or `None` to start them at the first body.	`None`
`rods`	`bool`	Whether to draw rods through the bodies.	`False`
`traced`	`Sequence[int] \| None`	The indices of the bodies whose trails are drawn, or `None` for every body.	`None`
`trail`	`int \| None`	The number of recent positions in a trail, 0 for no trail, or `None` for the whole path.	`_TRAIL_LENGTH`
`outline`	`Outline`	Static polylines, each an array of rows `(x, y)`, such as the walls of a table, or a function of the parameters and states by keyword that returns them from the first frame.	`()`
`marks`	`Marks`	Static points, such as fixed attracting centres, or a function of the parameters and states by keyword that returns them from the first frame.	`()`
`radius`	`float \| None`	The radius of the bodies, or `None` for a share of the extent of the view.	`None`
`path`	`str \| None`	The entity path of the element or agent group to draw, which also names it in the problem.	`None`
`recording`	`RecordingStream \| None`	The Rerun recording to log to, or `None` for the active recording of the thread.	`None`

Attributes:

Name	Type	Description
`history_`		The recent positions of the traced bodies, the oldest first.
`drawn_`		The entity paths whose outline and marks are logged.

Examples:

>>> from skcomplex.engine.viz import BodiesVisual
>>> BodiesVisual(('x', 'y'), trail=None).trail is None
True

Source code in src/skcomplex/engine/viz/_bodies.py

def __init__(
    self,
    positions: Positions,
    *,
    pivot: Sequence[float] | None = None,
    rods: bool = False,
    traced: Sequence[int] | None = None,
    trail: int | None = _TRAIL_LENGTH,
    outline: Outline = (),
    marks: Marks = (),
    radius: float | None = None,
    path: str | None = None,
    recording: rr.RecordingStream | None = None,
) -> None:
    self.positions = positions
    self.pivot = pivot
    self.rods = rods
    self.traced = traced
    self.trail = trail
    self.outline = outline
    self.marks = marks
    self.radius = radius
    self.path = path
    self.recording = recording

`CayleyVisual(states=None, low=None, high=None, *, path=None, recording=None)`

Bases: BaseVisual

Visual that logs every state of a lattice group on a group space as the nodes of its Cayley graph.

Sites sit on rings by word length, with one ring per radius and the identity at the centre, colored by state. Every chosen state is logged under <path>/<state> as GraphNodes at every frame, with the edges from every site g to g s for every generator s logged once as static GraphEdges.

Parameters:

Name	Type	Description	Default
`states`	`Sequence[str] \| None`	The states to log, or `None` for every state.	`None`
`low`	`float \| None`	The value of the darkest color, or `None` for the smallest value of every frame.	`None`
`high`	`float \| None`	The value of the brightest color, or `None` for the largest value of every frame.	`None`
`path`	`str \| None`	The entity path of the element or agent group to draw, which also names it in the problem.	`None`
`recording`	`RecordingStream \| None`	The Rerun recording to log to, or `None` for the active recording of the thread.	`None`

Attributes:

Name	Type	Description
`edges_`		The entity paths whose static edges are logged.

Examples:

>>> from skcomplex.engine.viz import CayleyVisual
>>> CayleyVisual(low=0, high=1)
CayleyVisual(high=1, low=0)

Source code in src/skcomplex/engine/viz/_cayley.py

def __init__(
    self,
    states: Sequence[str] | None = None,
    low: float | None = None,
    high: float | None = None,
    *,
    path: str | None = None,
    recording: rr.RecordingStream | None = None,
) -> None:
    self.states = states
    self.low = low
    self.high = high
    self.path = path
    self.recording = recording

`ExpectationVisual(states=None, low=None, high=None, history=None, *, slices=None, moments=None, path=None, recording=None)`

Bases: ImageVisual

Visual that logs the local expectations of operator elements and groups.

A group logs the expectation of the displayed local operator of every member, such as z, as an image of its lattice under <path>/<name>, with a space-time image under <path>/space_time/<name> in one dimension. A particle on sites logs the probability of every site the same way under probability. Any other element logs the expectation of each Hermitian local operator as a series under <path>/<name>.

Parameters:

Name	Type	Description	Default
`states`	`Sequence[str] \| None`	Unused, kept from `ImageVisual`.	`None`
`low`	`float \| None`	The value of the darkest color, or `None` for the smallest value of every frame.	`None`
`high`	`float \| None`	The value of the brightest color, or `None` for the largest value of every frame.	`None`
`history`	`int \| None`	The largest number of rows of the space-time image, or `None` for as many as sites, between 64 and 256.	`None`

Examples:

>>> from skcomplex.engine.viz import ExpectationVisual
>>> ExpectationVisual(low=-0.5, high=0.5)
ExpectationVisual(high=0.5, low=-0.5)

Source code in src/skcomplex/engine/viz/_images.py

def __init__(
    self,
    states: Sequence[str] | None = None,
    low: float | None = None,
    high: float | None = None,
    history: int | None = None,
    *,
    slices: Mapping[str | int, int] | None = None,
    moments: Sequence[int] | None = None,
    path: str | None = None,
    recording: rr.RecordingStream | None = None,
) -> None:
    self.states = states
    self.low = low
    self.high = high
    self.history = history
    self.slices = slices
    self.moments = moments
    self.path = path
    self.recording = recording

`HistogramVisual(color_by=None, color_range=None, radius=None, *, bins=BINS, shown=('agents', 'mean', 'std'), histogram_first=False, path=None, recording=None)`

Bases: AgentsVisual

Visual that logs the traits of agents, or the states of a group, without a space as histograms and statistics.

For every trait of the agents, a number per agent is taken: the value of a numeric trait, the total of a row of numbers such as the ones of a genome, or the size of a collection such as a vocabulary. The visual logs the histogram of these numbers as a BarChart under <path>/<trait>/histogram, over a range that widens to every value logged so far, with one bar per value when the values are few integers, and their mean and standard deviation as series under <path>/<trait>/mean and <path>/<trait>/std. Integer numbers, such as type labels, also log their number of distinct values under <path>/<trait>/distinct, and a group of at most ten agents logs the number of every agent as its own series under <path>/<trait>/agents. Traits of other kinds are left out. The states of the members of a group are logged the same way, one histogram per state.

Parameters:

Name	Type	Description	Default
`color_by`	`str \| None`	The trait whose histogram the first view shows, or `None` for the first trait of the agents.	`None`
`color_range`	`tuple[float, float] \| None`	The range of the histogram, or `None` for a range widened to every logged value.	`None`
`radius`	`float \| None`	Not used, kept for the options of agents visuals.	`None`
`bins`	`int`	The number of bins of the histograms.	`BINS`
`shown`	`Sequence[str]`	The series of the colored trait that the first view shows, among `'agents'`, `'mean'`, `'std'`, and `'distinct'`.	`('agents', 'mean', 'std')`
`histogram_first`	`bool`	Whether the histogram view comes before the time series view of the colored trait, for traits whose distribution matters more than its statistics, such as clustered opinions.	`False`
`path`	`str \| None`	The entity path of the element or agent group to draw, which also names it in the problem.	`None`
`recording`	`RecordingStream \| None`	The Rerun recording to log to, or `None` for the active recording of the thread.	`None`

Attributes:

Name	Type	Description
`spans_`		The range of the histogram of every trait logged so far, by entity path.

Examples:

>>> from skcomplex.engine.viz import HistogramVisual
>>> HistogramVisual(color_by='fitness').bins
20

Source code in src/skcomplex/engine/viz/_histograms.py

def __init__(
    self,
    color_by: str | None = None,
    color_range: tuple[float, float] | None = None,
    radius: float | None = None,
    *,
    bins: int = BINS,
    shown: Sequence[str] = ('agents', 'mean', 'std'),
    histogram_first: bool = False,
    path: str | None = None,
    recording: rr.RecordingStream | None = None,
) -> None:
    super().__init__(color_by=color_by, color_range=color_range, radius=radius, path=path, recording=recording)
    self.bins = bins
    self.shown = shown
    self.histogram_first = histogram_first

`ImageVisual(states=None, low=None, high=None, history=None, *, slices=None, moments=None, path=None, recording=None)`

Bases: BaseVisual

Visual that logs every state of a lattice group as an image colored by value, or a tensor in 3D and more.

A one-dimensional lattice also logs a space-time image under <path>/space_time/<state>, with one row per logged frame, the oldest at the top, and at most history rows. Its colors span the values of the rows it shows.

A state on a phase space of more than two axes can log a plane through slices. Its moments over the class axes log under <path>/<state>/moment_<order>, as a bar series over a one-dimensional position lattice and as an image over a two-dimensional one.

Parameters:

Name	Type	Description	Default
`states`	`Sequence[str] \| None`	The states to log, or `None` for every state.	`None`
`low`	`float \| None`	The value of the darkest color, or `None` for the smallest value of every frame.	`None`
`high`	`float \| None`	The value of the brightest color, or `None` for the largest value of every frame.	`None`
`history`	`int \| None`	The largest number of rows of the space-time image of a one-dimensional lattice, 0 for no space-time image, or `None` for as many rows as the lattice has sites, between 64 and 256.	`None`
`slices`	`Mapping[str \| int, int] \| None`	The index that every axis but two is fixed at, by the name of a class axis or the index of an axis, or `None` to log the whole state.	`None`
`moments`	`Sequence[int] \| None`	The orders of the moments over the class axes of a phase space to log, or `None` for none.	`None`
`path`	`str \| None`	The entity path of the element or agent group to draw, which also names it in the problem.	`None`
`recording`	`RecordingStream \| None`	The Rerun recording to log to, or `None` for the active recording of the thread.	`None`

Attributes:

Name	Type	Description
`rows_`		The recent rows of the space-time image of every state, by entity path.

Raises:

Type	Description
`ValidationError`	`slices` or `moments` are given for a group that is not on a phase space, or `slices` does not leave two axes.

Examples:

>>> from skcomplex.engine.viz import ImageVisual
>>> ImageVisual(low=0, high=1)
ImageVisual(high=1, low=0)

Source code in src/skcomplex/engine/viz/_images.py

def __init__(
    self,
    states: Sequence[str] | None = None,
    low: float | None = None,
    high: float | None = None,
    history: int | None = None,
    *,
    slices: Mapping[str | int, int] | None = None,
    moments: Sequence[int] | None = None,
    path: str | None = None,
    recording: rr.RecordingStream | None = None,
) -> None:
    self.states = states
    self.low = low
    self.high = high
    self.history = history
    self.slices = slices
    self.moments = moments
    self.path = path
    self.recording = recording

`MatrixVisual(variable='W', *, color_range=None, path=None, recording=None)`

Bases: BaseVisual

Visual that logs a matrix-valued state or parameter as an image colored by value, one image per frame.

The visual draws the variable variable of the element at path, or the state or parameter named <path>.<variable> of a problem without such an element, such as a trained matrix of a system that trains, under the entity path <path>/<variable>. The colors span the fixed range color_range when it is given and the range of the frame otherwise.

Parameters:

Name	Type	Description	Default
`variable`	`str`	The name of the matrix-valued state or parameter.	`'W'`
`color_range`	`tuple[float, float] \| None`	The values of the darkest and the brightest color, or `None` for the range of every frame.	`None`
`path`	`str \| None`	The entity path of the element, or the path the name of the variable starts with.	`None`
`recording`	`RecordingStream \| None`	The Rerun recording to log to, or `None` for the active recording of the thread.	`None`

Attributes:

Name	Type	Description
`name_`	`str`	The dotted name of the variable in the problem.
`shape_`	`tuple[int, ...]`	The shape of the matrix.

Raises:

Type	Description
`ValidationError`	The variable is not a name, or the problem has no matrix of that name.

Examples:

>>> from skcomplex.engine.compile import compile_system
>>> from skcomplex.engine.viz import MatrixVisual
>>> from skcomplex.models.computer_science.neural_networks import elman_network
>>> problem = compile_system(elman_network(n_bits=30))
>>> MatrixVisual('A', path='net/recurrence').check().prepare(problem).name_
'net/recurrence.A'

Source code in src/skcomplex/engine/viz/_matrices.py

def __init__(
    self,
    variable: str = 'W',
    *,
    color_range: tuple[float, float] | None = None,
    path: str | None = None,
    recording: rr.RecordingStream | None = None,
) -> None:
    super().__init__(path=path, recording=recording)
    self.variable = variable
    self.color_range = color_range

`MeshVisual(states=None, low=None, high=None, *, path=None, recording=None)`

Bases: BaseVisual

Visual that logs every state of a finite element field as a triangle mesh colored by value.

Triangle meshes are drawn flat with the value as their height, and tetrahedral meshes as points.

Parameters:

Name	Type	Description	Default
`states`	`Sequence[str] \| None`	The states to log, or `None` for every state.	`None`
`low`	`float \| None`	The value of the darkest color, or `None` for the smallest value of every frame.	`None`
`high`	`float \| None`	The value of the brightest color, or `None` for the largest value of every frame.	`None`
`path`	`str \| None`	The entity path of the element or agent group to draw, which also names it in the problem.	`None`
`recording`	`RecordingStream \| None`	The Rerun recording to log to, or `None` for the active recording of the thread.	`None`

Examples:

>>> from skcomplex.engine.viz import MeshVisual
>>> MeshVisual(low=0.0)
MeshVisual(low=0.0)

Source code in src/skcomplex/engine/viz/_meshes.py

def __init__(
    self,
    states: Sequence[str] | None = None,
    low: float | None = None,
    high: float | None = None,
    *,
    path: str | None = None,
    recording: rr.RecordingStream | None = None,
) -> None:
    self.states = states
    self.low = low
    self.high = high
    self.path = path
    self.recording = recording

`PhaseRingVisual(phase, position=None, *, path=None, recording=None)`

Bases: BaseVisual

Visual that logs the wrapped phases of a group of oscillators against their position as colored points.

Every member is a point at its position along the group and its phase wrapped into (-pi, pi], colored by the cyclic palette of phases, so a coherent stretch of oscillators shows as a flat run of one color and an incoherent stretch as scattered points. The points are logged under <path>/phases with the vertical axis up, one turn of phase spanning six tenths of the extent of the positions, and the other states as time series under <path>/<state>.

Parameters:

Name	Type	Description	Default
`phase`	`str`	The name of the state that holds the phase of every member.	required
`position`	`str \| None`	The name of a scalar state or of the first coordinate of a vector state that holds the position of every member, or `None` for the member index.	`None`
`path`	`str \| None`	The entity path of the element or agent group to draw, which also names it in the problem.	`None`
`recording`	`RecordingStream \| None`	The Rerun recording to log to, or `None` for the active recording of the thread.	`None`

Examples:

>>> from skcomplex.engine.viz import PhaseRingVisual
>>> PhaseRingVisual('theta').phase
'theta'

Source code in src/skcomplex/engine/viz/_rings.py

def __init__(
    self,
    phase: str,
    position: str | None = None,
    *,
    path: str | None = None,
    recording: rr.RecordingStream | None = None,
) -> None:
    self.phase = phase
    self.position = position
    self.path = path
    self.recording = recording

`PointsVisual(position, radius=None, color_by=None, color_range=None, states=None, *, trail=_TRAIL_LENGTH, path=None, recording=None)`

Bases: BaseVisual

Visual that logs a vector state as points, one per member of a group, and other states as time series.

Each state is logged as one batch, so a group of any size takes one log call per state and frame. Positions in two dimensions are logged with the second coordinate negated, since Rerun's 2D views point their vertical axis down, so the views draw them with the vertical axis up and show the negated value on hover. Without a given radius, the points take a share of the extent of the positions logged so far, smaller for larger groups. The extent and the count include every element drawn by a points visual of the same position state, so single particles that share a space, such as the masses of a chain, take one radius from the whole drawing. A group of at most ten points in two or three dimensions also logs the trail of its recent positions as line strips under <path>/trail, a quarter as wide as that share, whatever the radius.

Parameters:

Name	Type	Description	Default
`position`	`str`	The name of the vector state that holds the position.	required
`radius`	`float \| None`	The radius of the points, or `None` for a share of the extent of the positions.	`None`
`color_by`	`str \| None`	The name of a scalar state, or of a vector state whose norm, colors the points, or `None` for one color.	`None`
`color_range`	`tuple[float, float] \| None`	The values at the two ends of the color scale, or `None` for a range widened to every logged value.	`None`
`states`	`Sequence[str] \| None`	The names of the other states to log as time series, or `None` for all of them.	`None`
`trail`	`int`	The number of recent positions the trail of each point holds, or 0 for no trail.	`_TRAIL_LENGTH`
`path`	`str \| None`	The entity path of the element or agent group to draw, which also names it in the problem.	`None`
`recording`	`RecordingStream \| None`	The Rerun recording to log to, or `None` for the active recording of the thread.	`None`

Attributes:

Name	Type	Description
`history_`		The recent positions of the points, the oldest first.
`bounds_`		The lowest and highest coordinates of the positions logged so far, or `None`.
`span_`		The range of the colored values logged so far, or `None`.

Examples:

>>> from skcomplex.engine.viz import PointsVisual
>>> PointsVisual(position='x', color_by='v').color_by
'v'

Source code in src/skcomplex/engine/viz/_points.py

def __init__(
    self,
    position: str,
    radius: float | None = None,
    color_by: str | None = None,
    color_range: tuple[float, float] | None = None,
    states: Sequence[str] | None = None,
    *,
    trail: int = _TRAIL_LENGTH,
    path: str | None = None,
    recording: rr.RecordingStream | None = None,
) -> None:
    self.position = position
    self.radius = radius
    self.color_by = color_by
    self.color_range = color_range
    self.states = states
    self.trail = trail
    self.path = path
    self.recording = recording

`RerunObserver(application_id='skcomplex', *, spawn=False, connect=False, save_path=None, interval=1, blueprint=None, primary=None, parameters=False)`

Bases: BaseObserver

Observer that logs frames to Rerun, with entity paths that follow the system tree.

prepare(problem) creates the recording, builds the visual of every element and agent group from the visual its type declares, lays out their views, and sends the recording to its sinks. run(frame) logs a frame, and run(final=True) flushes the recording. Each logged frame sets the sim_time and step timelines, logs every element with its visual, logs every parameter up to a matrix under parameters/<name>, leaving out coupling tensors, whose entries no view can draw, and logs the renewals of renewal laws since the previous frame as text entries under renewals/<label>. A subclass logs entities of its own apart from the system's with _log_extra.

The default blueprint puts spatial views first and side by side, with time series views below them. Scalar elements of one type share a time series view with at most six series, and time series views show the whole run. The side panels are collapsed, the top panel is hidden, and the time panel follows the latest frame of the simulated time.

Parameters:

Name	Type	Description	Default
`application_id`	`str`	The Rerun application id.	`'skcomplex'`
`spawn`	`bool`	Whether to spawn the Rerun viewer installed with the running interpreter, or the one on `PATH`.	`False`
`connect`	`bool`	Whether to connect to a running Rerun viewer.	`False`
`save_path`	`str \| Path \| None`	The path of a `.rrd` file to save the recording to.	`None`
`interval`	`int`	The number of frames between logged frames.	`1`
`blueprint`	`Literal['default'] \| Blueprint \| None`	The layout of the viewer: `None` to let the viewer choose it, `'default'` for the default blueprint built from the views of the visuals, or a Rerun blueprint. It is sent with the recording, and written next to a saved recording as a `.rbl` file with the same stem.	`None`
`primary`	`str \| None`	The name or the origin of the view to put first in the default blueprint, with its row, or `None` for the first spatial view, or the first time series view without one.	`None`
`parameters`	`bool`	Whether the default blueprint has a time series view of the parameters.	`False`

Attributes:

Name	Type	Description
`recording_`		The Rerun recording stream.
`visuals_`		The prepared visuals of the elements and the agent groups, in the order they are logged.
`views_`		The views of the visuals, the observables, and the reporters, in the order of the default blueprint, so the first one is the primary view that shows the signature behaviour of the system.
`blueprint_`		The blueprint sent with the recording, or `None`.
`logged_frames_`		The number of frames logged.

Examples:

>>> import tempfile
>>> from pathlib import Path
>>> from skcomplex.core.system import System
>>> from skcomplex.models.biology.common.populations import ExponentialGrowthInteraction, PopulationElement
>>> from skcomplex.engine.runtime import Simulation
>>> from skcomplex.engine.viz import RerunObserver
>>> system = System(
...     elements=[PopulationElement('a', n=1)],
...     interactions=[ExponentialGrowthInteraction('g', target='a', r=1)],
... )
>>> path = Path(tempfile.mkdtemp()) / 'growth.rrd'
>>> simulation = Simulation(system, dt=0.1, observers=[RerunObserver('growth', save_path=path)])
>>> _ = simulation.check().prepare().run(until=1)
>>> path.exists()
True
>>> observer = RerunObserver('growth', save_path=path, blueprint='default')
>>> _ = Simulation(system, dt=0.1, observers=[observer]).check().prepare().run(until=1)
>>> path.with_suffix('.rbl').exists()
True

The default blueprint of a compiled problem, with a chosen view first:

>>> from skcomplex.engine.compile import compile_system
>>> from skcomplex.models import create
>>> problem = compile_system(create('gray_scott', shape=(16, 16)))
>>> observer = RerunObserver(blueprint='default', primary='cells/v').check().prepare(problem)
>>> [str(view.origin) for view in observer.blueprint_.root_container.contents]
['cells/v', 'cells/u']

Source code in src/skcomplex/engine/viz/_rerun.py

def __init__(
    self,
    application_id: str = 'skcomplex',
    *,
    spawn: bool = False,
    connect: bool = False,
    save_path: str | Path | None = None,
    interval: int = 1,
    blueprint: Literal['default'] | rrb.Blueprint | None = None,
    primary: str | None = None,
    parameters: bool = False,
) -> None:
    self.application_id = application_id
    self.spawn = spawn
    self.connect = connect
    self.save_path = save_path
    self.interval = interval
    self.blueprint = blueprint
    self.primary = primary
    self.parameters = parameters

`ScalarsVisual(components=None, *, path=None, recording=None)`

Bases: BaseVisual

Visual that logs each state component of an element as a time series.

Every state gets static series colors from a categorical palette, by its position among the states of every element of the problem, so the series of one view are told apart. The lag states that keep the past values of a delayed state are left out.

Parameters:

Name	Type	Description	Default
`components`	`Sequence[int] \| None`	The indices of the components of vector states to log, or `None` for every component.	`None`
`path`	`str \| None`	The entity path of the element or agent group to draw, which also names it in the problem.	`None`
`recording`	`RecordingStream \| None`	The Rerun recording to log to, or `None` for the active recording of the thread.	`None`

Attributes:

Name	Type	Description
`styled_`		The entity paths whose series colors are logged.

Examples:

>>> from skcomplex.engine.viz import ScalarsVisual
>>> ScalarsVisual()
ScalarsVisual()

Source code in src/skcomplex/engine/viz/_scalars.py

def __init__(
    self,
    components: Sequence[int] | None = None,
    *,
    path: str | None = None,
    recording: rr.RecordingStream | None = None,
) -> None:
    self.components = components
    self.path = path
    self.recording = recording

`SiteVisual(states=None, low=None, high=None, *, path=None, recording=None)`

Bases: BaseVisual

Visual that logs every state of a lattice group that is not square as colored sites.

A triangular lattice is logged as Points2D at the site positions, with radii that cover the hexagonal cells of the sites. A lattice group on a network is logged as GraphNodes colored by state, at the pos attributes of the nodes or a seeded spring layout, with its GraphEdges logged once as static data. A variable group on the nodes of a network whose topology changes logs the nodes present at every frame, placed by the force layout of the graph view, and its edges at every frame where they change.

Parameters:

Name	Type	Description	Default
`states`	`Sequence[str] \| None`	The states to log, or `None` for every state.	`None`
`low`	`float \| None`	The value of the darkest color, or `None` for the smallest value of every frame.	`None`
`high`	`float \| None`	The value of the brightest color, or `None` for the largest value of every frame.	`None`
`path`	`str \| None`	The entity path of the element or agent group to draw, which also names it in the problem.	`None`
`recording`	`RecordingStream \| None`	The Rerun recording to log to, or `None` for the active recording of the thread.	`None`

Attributes:

Name	Type	Description
`edges_`		The entity paths whose static edges are logged.
`changing_`		The hash of the latest logged edges of every changing network, by entity path.

Examples:

>>> from skcomplex.engine.viz import SiteVisual
>>> SiteVisual(low=0, high=2)
SiteVisual(high=2, low=0)

Source code in src/skcomplex/engine/viz/_sites.py

def __init__(
    self,
    states: Sequence[str] | None = None,
    low: float | None = None,
    high: float | None = None,
    *,
    path: str | None = None,
    recording: rr.RecordingStream | None = None,
) -> None:
    self.states = states
    self.low = low
    self.high = high
    self.path = path
    self.recording = recording