Pole-Zero Map Visualization

This module provides the PoleZeroMap class for creating pole-zero map visualizations of control systems.

PoleZeroMap Class

class PoleZeroMap(system, x_range=None, y_range=None, dashed_axis=False, y_axis_label=None, x_axis_label=None, font_size_labels=28, markers_size=0.15, use_math_tex_labels=True, **kwargs)[source]

Bases: VGroup

__init__(system, x_range=None, y_range=None, dashed_axis=False, y_axis_label=None, x_axis_label=None, font_size_labels=28, markers_size=0.15, use_math_tex_labels=True, **kwargs)[source]

Generates a pole-zero map as a Manim VGroup for continuous- or discrete-time systems.

This class takes a symbolic transfer function (numerator and denominator) and visualizes its poles and zeros in the complex plane. It supports customizable axes, automatic scaling, optional unit circle display (for discrete-time systems), and labeled axes.

Parameters:

  • system (various) – System representation, which can be one of: - scipy.signal.lti or transfer function coefficients (list/tuple of arrays) - Symbolic expressions for numerator/denominator (using ‘s’ as variable) - Tuple of (numerator_expr, denominator_expr) as strings or sympy expressions

  • x_range (list[float] | None) – Range for the real axis in the form [min, max, step]. If None, automatically determined.

  • y_range (list[float] | None) – Range for the imaginary axis in the form [min, max, step]. If None, automatically determined.

  • dashed_axis (bool) – Whether the axis lines are dashed

  • x_axis_label (str) – Label for the real axis.

  • y_axis_label (str) – Label for the imaginary axis.

  • font_size_labels (int) – Font size for axis labels (default: 28).

  • show_unit_circle (bool) – Whether to show the unit circle (used for analyzing discrete-time systems).

  • **kwargs (Any) – Additional keyword arguments passed to the VGroup constructor.

Returns:

A Manim VGroup containing the complex axis, poles, zeros, optional unit circle, and tick labels.

Return type:

VGroup

add_stability_regions(show_stable=True, show_unstable=True, stable_label='Stable', unstable_label='Unstable', stable_color=ManimColor('#58C4DD'), unstable_color=ManimColor('#FC6255'), use_mathtex=False, fill_opacity=0.2, label_font_size=30, add_directly=True)[source]

Create the stability regions based on system type

title(text, font_size=25, color=ManimColor('#FFFFFF'), use_math_tex=False)[source]

Add or update the title of the pole-zero plot.

Parameters:

  • text (str) – The title text

  • font_size (float) – Font size of the title

  • color (Manim color) – Color of the title

  • use_math_tex (bool) – Whether to render as MathTex

__init__(system, x_range=None, y_range=None, dashed_axis=False, y_axis_label=None, x_axis_label=None, font_size_labels=28, markers_size=0.15, use_math_tex_labels=True, **kwargs)[source]

Generates a pole-zero map as a Manim VGroup for continuous- or discrete-time systems.

This class takes a symbolic transfer function (numerator and denominator) and visualizes its poles and zeros in the complex plane. It supports customizable axes, automatic scaling, optional unit circle display (for discrete-time systems), and labeled axes.

Parameters:

  • system (various) – System representation, which can be one of: - scipy.signal.lti or transfer function coefficients (list/tuple of arrays) - Symbolic expressions for numerator/denominator (using ‘s’ as variable) - Tuple of (numerator_expr, denominator_expr) as strings or sympy expressions

  • x_range (list[float] | None) – Range for the real axis in the form [min, max, step]. If None, automatically determined.

  • y_range (list[float] | None) – Range for the imaginary axis in the form [min, max, step]. If None, automatically determined.

  • dashed_axis (bool) – Whether the axis lines are dashed

  • x_axis_label (str) – Label for the real axis.

  • y_axis_label (str) – Label for the imaginary axis.

  • font_size_labels (int) – Font size for axis labels (default: 28).

  • show_unit_circle (bool) – Whether to show the unit circle (used for analyzing discrete-time systems).

  • **kwargs (Any) – Additional keyword arguments passed to the VGroup constructor.

Returns:

A Manim VGroup containing the complex axis, poles, zeros, optional unit circle, and tick labels.

Return type:

VGroup

add_stability_regions(show_stable=True, show_unstable=True, stable_label='Stable', unstable_label='Unstable', stable_color=ManimColor('#58C4DD'), unstable_color=ManimColor('#FC6255'), use_mathtex=False, fill_opacity=0.2, label_font_size=30, add_directly=True)[source]

Create the stability regions based on system type

animation_overrides = {}
background_image: Image | str | None
background_stroke_color: ManimColor
background_stroke_opacity: float
background_stroke_width: float
cap_style: CapStyleType
close_new_points: bool
joint_type: LineJointType
make_smooth_after_applying_functions: bool
n_points_per_cubic_curve: int
pre_function_handle_to_anchor_scale_factor: float
scale(scale_factor, **kwargs)[source]

Scale the PoleZeroMap group, ensuring stroke widths of components (markers, axes, box, ticks) are scaled proportionally.

shade_in_3d: bool
submobjects: list[VMobject]
title(text, font_size=25, color=ManimColor('#FFFFFF'), use_math_tex=False)[source]

Add or update the title of the pole-zero plot.

Parameters:

  • text (str) – The title text

  • font_size (float) – Font size of the title

  • color (Manim color) – Color of the title

  • use_math_tex (bool) – Whether to render as MathTex

tolerance_for_point_equality: float

System Input Formats

The PoleZeroMap class accepts multiple system representation formats:

  1. Coefficient tuples: (numerator_coeffs, denominator_coeffs)

  2. Symbolic expressions: Using ‘s’ or ‘z’ as variables

  3. Transfer function strings: "s/(s^2 + 2*s + 1)" or "(z-1)/(z^2 - 0.5*z)"

  4. Sympy expressions: Direct symbolic transfer functions

Plot Features

  • Automatic system type detection: Continuous-time (s-domain) vs Discrete-time (z-domain)

  • Automatic range determination: Based on pole and zero locations

  • Customizable axes: Manual range specification available

  • Stability regions: Visual indication of stable/unstable regions

  • Unit circle: Automatic display for discrete-time systems

  • Pole/zero markers: Poles as red crosses (×), zeros as blue circles (○)

  • Axis labels: Automatic labeling based on system type

System Type Detection

The class automatically detects system type:

  • Continuous-time systems: Use ‘s’ variable, show left-half plane stability

  • Discrete-time systems: Use ‘z’ variable, show unit circle stability

Stability Regions

  • Continuous-time: Left-half plane is stable, right-half plane is unstable

  • Discrete-time: Inside unit circle is stable, outside is unstable

Notes

  • Internal methods (starting with _) are not intended for user use

  • The class automatically handles range determination and axis scaling

  • Pole and zero markers are sized proportionally to the plot dimensions

  • Stability regions can be customized with different colors and opacities