API Reference

system_design.zGridTool.cli

Command-line interface for system_design.zGridTool.

The CLI preserves the original z-grid workflow while adding a sphinx-skel helper for generating conservative, GitHub Pages friendly Sphinx documentation files.

Supported execution styles

  • python -m system_design.zGridTool.cli --T 0.1

  • python -m system_design.zGridTool.cli run --T 0.1

  • python system_design/zGridTool/cli.py --T 0.1

  • python -m system_design.zGridTool.cli sphinx-skel system_design/zGridTool/docs

system_design.zGridTool.cli.build_parser()[source]

Build the command-line parser.

Return type:

ArgumentParser

system_design.zGridTool.cli.main(argv=None)[source]

Run the zGridTool command-line interface.

Parameters:

argv (list[str] | None)

Return type:

int

system_design.zGridTool.apis

Public API surface for system_design.zGridTool

class system_design.zGridTool.apis.RunRequest(T: 'Optional[float]' = None, fs: 'Optional[float]' = None, zetas: 'List[float]' = <factory>, wd_over_ws: 'List[float]' = <factory>, wnT: 'List[float]' = <factory>, theta_max: 'float' = 3.141592653589793, settling_sigma: 'Optional[float]' = None, pz_files: 'List[str]' = <factory>, backend: 'str' = 'mpl', png: 'str' = 'zgrid.png', plotly_html: 'Optional[str]' = None, width: 'int' = 900, height: 'int' = 900, dpi: 'int' = 150, dark: 'bool' = False, theme: 'str' = 'plotly_white', legend_mode: 'str' = 'minimal', legend_loc: 'str' = 'bottom', title: 'str' = 'z-plane design grid', title_mode: 'str' = 'auto', responsive: 'bool' = True, export_csv_prefix: 'Optional[str]' = None, verbose: 'bool' = False)[source]

Bases: object

Parameters:

  • T (float | None)

  • fs (float | None)

  • zetas (List[float])

  • wd_over_ws (List[float])

  • wnT (List[float])

  • theta_max (float)

  • settling_sigma (float | None)

  • pz_files (List[str])

  • backend (str)

  • png (str)

  • plotly_html (str | None)

  • width (int)

  • height (int)

  • dpi (int)

  • dark (bool)

  • theme (str)

  • legend_mode (str)

  • legend_loc (str)

  • title (str)

  • title_mode (str)

  • responsive (bool)

  • export_csv_prefix (str | None)

  • verbose (bool)

T: float | None = None
backend: str = 'mpl'
dark: bool = False
dpi: int = 150
export_csv_prefix: str | None = None
fs: float | None = None
height: int = 900
legend_loc: str = 'bottom'
legend_mode: str = 'minimal'
plotly_html: str | None = None
png: str = 'zgrid.png'
pz_files: List[str]
responsive: bool = True
settling_sigma: float | None = None
theme: str = 'plotly_white'
theta_max: float = 3.141592653589793
title: str = 'z-plane design grid'
title_mode: str = 'auto'
verbose: bool = False
wd_over_ws: List[float]
width: int = 900
wnT: List[float]
zetas: List[float]
class system_design.zGridTool.apis.RunResult(png_path: 'Optional[str]' = None, html_path: 'Optional[str]' = None, csv_prefix: 'Optional[str]' = None)[source]

Bases: object

Parameters:

  • png_path (str | None)

  • html_path (str | None)

  • csv_prefix (str | None)

csv_prefix: str | None = None
html_path: str | None = None
png_path: str | None = None

system_design.zGridTool.app

App orchestration for zGridTool.

class system_design.zGridTool.app.ZGridApp[source]

Bases: object

run(req)[source]
Parameters:

req (RunRequest)

Return type:

RunResult

system_design.zGridTool.core

Math core for z-grid curves.

system_design.zGridTool.core.curve_const_wnT(wnT, npts=1201)[source]
Parameters:

  • wnT (float)

  • npts (int)

system_design.zGridTool.core.polar_to_cart(r, theta)[source]
Parameters:

  • r (numpy.ndarray)

  • theta (numpy.ndarray)

Return type:

Tuple[numpy.ndarray, numpy.ndarray]

system_design.zGridTool.core.ray_theta(theta, rmax=1.0)[source]
Parameters:

  • theta (float)

  • rmax (float)

system_design.zGridTool.core.ring_points(radius, n=721)[source]
Parameters:

  • radius (float)

  • n (int)

system_design.zGridTool.core.spiral_const_zeta(zeta, theta_max, npts=1501)[source]
Parameters:

  • zeta (float)

  • theta_max (float)

  • npts (int)

system_design.zGridTool.io

I/O helpers for z/pole-zero overlays and parsing.

class system_design.zGridTool.io.PZ(z: 'complex', kind: 'str', label: 'Optional[str]' = None)[source]

Bases: object

Parameters:

  • z (complex)

  • kind (str)

  • label (str | None)

kind: str
label: str | None = None
z: complex
system_design.zGridTool.io.parse_num_list(xs)[source]
Parameters:

xs (Iterable[str])

Return type:

List[float]

system_design.zGridTool.io.pretty_list(xs)[source]
Parameters:

xs (Iterable[float])

Return type:

str

system_design.zGridTool.io.read_pz_any(path)[source]
Parameters:

path (Path)

Return type:

List[PZ]

system_design.zGridTool.io.read_pz_csv(path)[source]
Parameters:

path (Path)

Return type:

List[PZ]

system_design.zGridTool.io.read_pz_json(path)[source]
Parameters:

path (Path)

Return type:

List[PZ]

system_design.zGridTool.io.resolve_overlay_paths(names)[source]
Parameters:

names (Iterable[str])

Return type:

List[Path]

system_design.zGridTool.io.to_complex(s)[source]
Parameters:

s (str)

Return type:

complex

system_design.zGridTool.utils

Utilities and decorators for system_design.zGridTool.

system_design.zGridTool.utils.ensure_in_path(name)[source]
Parameters:

name (str)

Return type:

Path

system_design.zGridTool.utils.ensure_out_path(name)[source]
Parameters:

name (str | None)

Return type:

Path | None

system_design.zGridTool.utils.log_call(fn)[source]

Simple decorator that logs call entry/exit for debugging/test visibility.

Parameters:

fn (F)

Return type:

F

system_design.zGridTool.design

Rendering and CSV export.

class system_design.zGridTool.design.Style(zeta_color: 'str' = '#1f77b4', wn_color: 'str' = '#2ca02c', ray_color: 'str' = '#ff7f0e', pole_color: 'str' = '#d62728', zero_edge: 'str' = '#1f77b4', zero_face: 'str' = '#ffffff')[source]

Bases: object

Parameters:

  • zeta_color (str)

  • wn_color (str)

  • ray_color (str)

  • pole_color (str)

  • zero_edge (str)

  • zero_face (str)

pole_color: str = '#d62728'
ray_color: str = '#ff7f0e'
wn_color: str = '#2ca02c'
zero_edge: str = '#1f77b4'
zero_face: str = '#ffffff'
zeta_color: str = '#1f77b4'
system_design.zGridTool.design.draw_mpl(T, zetas, wd_over_ws, wnT, theta_max, settling_sigma, pzs, style, width, height, dpi, dark, title, export_prefix)[source]
Parameters:

  • T (float)

  • zetas (List[float])

  • wd_over_ws (List[float])

  • wnT (List[float])

  • theta_max (float)

  • settling_sigma (float | None)

  • pzs (List[PZ])

  • style (Style)

  • width (int)

  • height (int)

  • dpi (int)

  • dark (bool)

  • title (str)

  • export_prefix (Path | None)

Return type:

matplotlib.pyplot.Figure

system_design.zGridTool.design.draw_plotly(T, zetas, wd_over_ws, wnT, theta_max, settling_sigma, pzs, title, width, height, legend_mode, legend_loc, responsive, theme)[source]
Parameters:

  • T (float)

  • zetas (List[float])

  • wd_over_ws (List[float])

  • wnT (List[float])

  • theta_max (float)

  • settling_sigma (float | None)

  • pzs (List[PZ])

  • title (str)

  • width (int)

  • height (int)

  • legend_mode (str)

  • legend_loc (str)

  • responsive (bool)

  • theme (str)