egttools.plotting.Simplex3D

class Simplex3D(figure_size=(700, 600))

Bases: object

3D simplex (tetrahedron) visualisation for 4-strategy evolutionary games.

Interior dynamics are shown by adding cross-sectional slices at a fixed strategy value. Each slice is a triangle embedded in 3D; the replicator dynamics on that slice are drawn as cone-arrow glyphs.

The figure is a Plotly go.Figure with a single go.Scene (3D axes). Call show() to display it in a notebook or browser, or use .figure to access the underlying Plotly object for further customisation.

Parameters:

figure_size (Tuple[int, int]) – Width and height of the Plotly figure in pixels.

Examples

>>> import numpy as np
>>> from egttools.plotting import Simplex3D
>>> def gradient(b):
...     # replicator dynamics for a 4-strategy game
...     payoffs = np.array([[1,0,0,0],[0,2,0,0],[0,0,3,0],[0,0,0,4]])
...     f = b @ payoffs          # mean fitness per strategy
...     fbar = b @ f             # mean population fitness
...     return b * (f - fbar)
>>> s = Simplex3D()
>>> (s.draw_tetrahedron()
...   .draw_slice(fixed_strategy=0, value=0.25,
...               gradient_fn=gradient, n_grid=8, n_arrows=6)
...   .add_vertex_labels(['A', 'B', 'C', 'D'])
...   .show())

Methods

add_vertex_labels	Add text labels near the four vertices.
build	Assemble and return the Plotly Figure.
draw_slice	Add a cross-sectional slice at b[fixed_strategy] = value.
draw_stationary_distribution	Draw the stationary distribution as transparent spheres in 3D.
draw_stationary_points	Draw stationary points inside or on the boundary of the tetrahedron.
draw_streamlines	Integrate and draw free 3D streamlines, inspired by matplotlib streamplot.
draw_tetrahedron	Draw the wireframe and optionally semi-transparent faces.
draw_trajectory	Draw a trajectory curve inside the tetrahedron.
show	Display the figure in a browser or Jupyter notebook.

Attributes

figure

The assembled Plotly Figure with colorbar (builds on first access).

__init__(figure_size=(700, 600))

add_vertex_labels(labels, fontsize=16, color='black', offset=0.06)

Add text labels near the four vertices.

Parameters:

• labels (sequence of str) – Four labels in strategy order (0–3).

• fontsize (int) – Font size in points.

• color (str) – Text colour.

• offset (float) – How far to push each label away from the centroid, in data units.

Return type:

Simplex3D

build(colorbar=True, colorbar_label='gradient of selection', colorbar_thickness=15, colorbar_len=0.5)

Assemble and return the Plotly Figure.

Parameters:

• colorbar (bool) – Whether to add a colorbar for the gradient magnitude scale. Only shown when a colorscale was used in draw_slice or draw_streamlines. Default True.

• colorbar_label (str) – Title shown next to the colorbar.

• colorbar_thickness (int) – Colorbar width in pixels.

• colorbar_len (float) – Colorbar length as a fraction of the plot height.

Return type:

Figure

draw_slice(fixed_strategy, value, gradient_fn=None, n_grid=10, n_seeds=5, slice_color='orange', arrow_color='#c0392b', min_line_width=1.5, max_line_width=5.0, cone_scale=0.008, arrow_fraction=0.5, colorscale='Viridis', show_slice_mesh=True, min_distance=0.04, dt=0.005, max_steps=400)

Add a cross-sectional slice at b[fixed_strategy] = value.

The slice is a filled triangle embedded in 3D. If gradient_fn is given, the in-plane dynamics are visualised as a 2D streamplot embedded on the slice — constrained integration, one arrowhead per line at the mid-point, linewidth and colour both encoding magnitude, and a density filter that prevents overlapping lines. This matches the appearance of Simplex2D’s streamplot.

Parameters:

• fixed_strategy (int) – Index of the strategy to fix (0–3).

• value (float) – Value of the fixed strategy in [0, 1).

• gradient_fn (callable, optional) – f(b) -> db/dt. Receives a 1-D array of shape (4,) and returns an array of the same shape.

• n_grid (int) – Resolution of the triangular mesh used to fill the slice.

• n_seeds (int) – Seed grid resolution along each edge of the sub-simplex.

• slice_color (str) – CSS colour of the slice fill panel.

• arrow_color (str) – Flat colour for lines and cones when colorscale is None.

• min_line_width (float) – Narrowest shaft width (pixels), at minimum magnitude.

• max_line_width (float) – Widest shaft width (pixels), at maximum magnitude.

• cone_scale (float) – Cone head length in data units.

• arrow_fraction (float) – Position of the arrowhead along each streamline (0 = start, 1 = end, 0.5 = mid-point, matching matplotlib streamplot).

• colorscale (str) – Plotly colorscale for shaft and cone colouring by magnitude.

• show_slice_mesh (bool) – Whether to draw the filled triangular panel.

• min_distance (float) – Minimum Cartesian distance between streamlines (density mask).

• dt (float) – Arc-length step size for integration.

• max_steps (int) – Maximum integration steps per streamline.

Return type:

Simplex3D

draw_stationary_distribution(stationary_distribution, population_size, colorscale='Greys', opacity_scale=3.0, min_opacity=0.0, max_opacity=0.9, marker_size=6.0, threshold=0.0, top_k=None, colorbar=True, colorbar_label='stationary distribution')

Draw the stationary distribution as transparent spheres in 3D.

Each population state is a point in the interior or on the boundary of the tetrahedron. Marker opacity and colour both encode the stationary probability, so high-probability states (near attractors) are opaque and vivid while low-probability states fade out.

To avoid visual clutter only states above threshold are shown, and optionally only the top top_k by probability.

Parameters:

• stationary_distribution (np.ndarray, shape (nb_states,)) – Stationary probabilities in the order produced by egt.sample_simplex(i, population_size, 4) for i=0..nb_states-1.

• population_size (int) – Population size Z used when computing the distribution.

• colorscale (str) – Plotly colorscale for marker colour (e.g. 'Reds', 'Hot').

• opacity_scale (float) – Controls how steeply opacity rises with probability. Higher values make only the very brightest states visible.

• min_opacity (float) – Minimum marker opacity (for the lowest shown probability).

• max_opacity (float) – Maximum marker opacity.

• marker_size (float) – Diameter of each sphere in pixels.

• threshold (float) – States with probability below this fraction of the maximum are not drawn. 0 = draw all states.

• top_k (int, optional) – If given, draw only the top_k highest-probability states.

• colorbar (bool) – Whether to add a colorbar for the distribution.

• colorbar_label (str) – Colorbar title.

Return type:

Simplex3D

draw_stationary_points(points, stability=None, stable_color='black', unstable_color='white', saddle_color='grey', size=8.0)

Draw stationary points inside or on the boundary of the tetrahedron.

Parameters:

• points (np.ndarray, shape (K, 4)) – Barycentric coordinates of each stationary point.

• stability (sequence of int, optional) – Stability label per point: 1 = stable, -1 = unstable, 0 = saddle. If None all points are drawn with stable_color.

• stable_color (str) – Marker colours for each stability class.

• unstable_color (str) – Marker colours for each stability class.

• saddle_color (str) – Marker colours for each stability class.

• size (float) – Marker size in pixels.

Return type:

Simplex3D

draw_streamlines(gradient_fn, seeds=None, fixed_strategy=None, fixed_value=None, n_seeds=5, colorscale='Viridis', arrow_color='#c0392b', min_line_width=1.5, max_line_width=5.0, cone_scale=0.008, arrow_fraction=0.5, dt=0.005, max_steps=600, min_distance=0.04)

Integrate and draw free 3D streamlines, inspired by matplotlib streamplot.

Mimics matplotlib’s streamplot behaviour in 3D:

• Uniform coverage — new streamlines are rejected if their seed is within min_distance (in Cartesian data units) of any already-drawn point, so lines are spread evenly rather than clumped.

• One arrowhead per streamline — placed at arrow_fraction of the total arc-length (default 50 %, i.e. mid-point), exactly as streamplot places its arrow near the middle of each line.

• Linewidth encodes speed — each streamline’s width scales linearly with its mean gradient magnitude between min_line_width and max_line_width, analogous to streamplot’s linewidth parameter when set to a speed array.

• Color encodes speed — colorscale maps local magnitude to colour, interpolated per-vertex along the shaft.

Parameters:

• gradient_fn (callable) – f(b) -> db/dt, shape (4,) → (4,).

• seeds (np.ndarray, shape (K, 4), optional) – Explicit seed points. When provided the density filter is still applied, so some seeds may be skipped.

• fixed_strategy (int, optional) – Strategy index for automatic seed generation on a slice plane.

• fixed_value (float, optional) – Slice value for automatic seed generation.

• n_seeds (int) – Grid resolution for automatic seed generation.

• colorscale (str) – Plotly colorscale for shaft/cone colouring by magnitude.

• arrow_color (str) – Flat colour when colorscale is None.

• min_line_width (float) – Narrowest shaft width (pixels), used at minimum magnitude.

• max_line_width (float) – Widest shaft width (pixels), used at maximum magnitude.

• cone_scale (float) – Cone head length in data units.

• arrow_fraction (float) – Position of the arrowhead along each streamline as a fraction of total arc-length (0 = start, 1 = end, 0.5 = mid-point).

• dt (float) – Arc-length step size for integration.

• max_steps (int) – Maximum integration steps per streamline.

• min_distance (float) – Minimum Cartesian distance between any two streamline points from different streamlines. Acts as the density mask from streamplot.

Return type:

Simplex3D

draw_tetrahedron(edge_color='#111111', edge_width=5.0, face_color='lightblue', face_opacity=0.05)

Draw the wireframe and optionally semi-transparent faces.

Parameters:

• edge_color (str) – Colour of the 6 edges.

• edge_width (float) – Width of the edges in pixels.

• face_color (str) – Fill colour of the 4 triangular faces.

• face_opacity (float) – Opacity of the faces (0 = invisible, 1 = opaque). Keep low so interior slices remain visible.

Return type:

Simplex3D

draw_trajectory(points, color='blue', width=4.0, name='')

Draw a trajectory curve inside the tetrahedron.

Parameters:

• points (np.ndarray, shape (T, 4)) – Sequence of barycentric coordinates along the trajectory.

• color (str) – Line colour.

• width (float) – Line width in pixels.

• name (str) – Label shown in the Plotly legend.

Return type:

Simplex3D

show(colorbar=True, **kwargs)

Display the figure in a browser or Jupyter notebook.

Parameters:

• colorbar (bool) – Whether to include the colorbar. Default True.

• **kwargs – Forwarded to build().

Return type:

None

__annotations__ = {}

property figure: Figure

The assembled Plotly Figure with colorbar (builds on first access).