# doc-cache created by Octave 11.3.0
# name: cache
# type: cell
# rows: 3
# columns: 28
# name: <cell-element>
# type: sq_string
# elements: 1
# length: 14
dsp_audio_demo


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 729
 -- Function File: dsp_audio_demo (PARENT_FIG, B, A, FS_FILTER)
     Open an audio demo window.  Load a WAV file, apply the designed filter,
     play original / filtered audio, and display waveforms and spectrograms side
     by side.

     The loaded audio is cached on PARENT_FIG, so going back to the main window,
     changing the design and reopening the demo brings the same file straight
     back - re-filtered with the new coefficients, without a second trip through
     the file dialog.  The cache lives and dies with the main window.

     The spectrogram frequency axis follows the tool-wide unit setting
     (‘dsp_freq_axis_hz’); the demo carries its own toggle button, like the
     detailed analysis window.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 26
Open an audio demo window.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 19
dsp_check_stability


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 785
 -- Function File: S = dsp_check_stability (B, A)
     Analyse the BIBO stability of a discrete-time filter given its
     transfer-function coefficients B (numerator) and A (denominator).

     Returns a struct S with the fields:
     ‘poles’
          Column vector of filter poles (roots of A).
     ‘radii’
          Absolute values of each pole.
     ‘max_radius’
          Radius of the pole closest to or outside the unit circle.
     ‘margin’
          Distance from the largest-radius pole to the unit circle (1 -
          max_radius).
     ‘stable’
          Boolean — true when every pole lies strictly inside the unit circle.
     ‘status’
          Human-readable string: ‘"STABLE"’, ‘"MARGINALLY STABLE"’, or
          ‘"UNSTABLE"’.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
Analyse the BIBO stability of a discrete-time filter given its transfer-funct...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 15
dsp_code_export


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 215
 -- Function File: dsp_code_export (H)
     Open an export window to generate and save filter coefficients as
     MATLAB/Octave, C, or Python code.  The window shows a live preview and
     allows saving to a file.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
Open an export window to generate and save filter coefficients as MATLAB/Octa...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 18
dsp_compare_window


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 233
 -- Function File: dsp_compare_window (MAIN_H)
     Open a comparison window that overlays the responses of two filters.  Each
     filter can be sourced from the current design or loaded from a previously
     saved ‘.fil’ file.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 68
Open a comparison window that overlays the responses of two filters.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 16
dsp_compute_f3db


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 1090
 -- Function File: STR = dsp_compute_f3db (H, WN)
 -- Function File: STR = dsp_compute_f3db (H, WN, FS)
 -- Function File: [STR, WN_CROSS] = dsp_compute_f3db (...)
     Return a human-readable string describing the -3 dB crossing frequencies of
     a frequency response H sampled at normalized frequencies WN (in units of
     \times\pi rad/sample, so wn \in [0, 1] where 1 corresponds to the Nyquist
     frequency).

     When a valid sampling frequency FS is supplied _and_ the tool-wide axis
     mode is Hz (‘dsp_freq_axis_hz’), the crossings are reported in Hz - or kHz
     once the Nyquist frequency reaches 1 kHz, the same threshold
     ‘dsp_freq_ticks’ uses for its tick labels.  Without FS the normalized form
     is always used, so callers that deliberately stay normalized (the
     comparison window) need no change.

     The second output WN_CROSS returns the crossings as raw normalized values,
     for callers that need to do their own formatting (the HTML report).  It is
     empty when there is no crossing.

     See also: dsp_freq_axis_hz, dsp_freq_ticks.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
Return a human-readable string describing the -3 dB crossing frequencies of a...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 18
dsp_compute_filter


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 611
 -- Function File: [B, A] = dsp_compute_filter (FS, FC, FC2, N, TYPE_IDX,
          TOPO_IDX, ARCH_IDX, RP, RS)
     Compute filter coefficients from UI parameters.  ARCH_IDX: 1=IIR (default),
     2=FIR TYPE_IDX: 1=lowpass, 2=highpass, 3=bandpass, 4=bandstop IIR TOPO_IDX:
     1=Butterworth, 2=Chebyshev I, 3=Chebyshev II, 4=Elliptic FIR TOPO_IDX:
     1=Rectangular, 2=Hamming, 3=Hanning, 4=Blackman, 5=Kaiser,
     6=Parks-McClellan, 7=Least-Squares The names matching these indices come
     from ‘dsp_topo_names’.  RP: passband ripple in dB (default 3) RS: stopband
     attenuation in dB (default 40)


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 47
Compute filter coefficients from UI parameters.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 19
dsp_design_callback


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 189
 -- Function File: dsp_design_callback (H)
     Design button handler.  Reads filter parameters from the GUI, computes the
     filter, plots responses, and updates the stability indicator.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 22
Design button handler.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 13
dsp_draw_mask


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 263
 -- Function File: dsp_draw_mask (AX, B, A, FS, FC, FC2, TYPE_IDX, RP, RS)
     Redraw the magnitude response with a specification mask overlay.  Forbidden
     zones are shaded light red; allowed passband is light green.  The response
     curve is drawn on top.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 64
Redraw the magnitude response with a specification mask overlay.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 15
dsp_draw_zplane


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 235
 -- Function File: dsp_draw_zplane (AX, ZEROS_Z, POLES_Z, TITLE_STR)
     Draw the unit circle, guide lines, zeros, and poles on the given axes
     handle.  Used by both the integrated P/Z editor and the standalone
     ‘pz_tool’.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 77
Draw the unit circle, guide lines, zeros, and poles on the given axes handle.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 19
dsp_export_callback


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 170
 -- Function File: dsp_export_callback (H)
     Export the current filter coefficients to the base workspace as
     ‘num_coeffs’, ‘den_coeffs’, and ‘fs_val’.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 84
Export the current filter coefficients to the base workspace as ‘num_coeffs’,...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 16
dsp_filter_order


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 609
 -- Function File: N = dsp_filter_order (B, A)
     Return the realized order of the digital filter with numerator B and
     denominator A.

     The order is ‘max (numel (b), numel (a)) - 1’, i.e.  the degree of the
     higher-degree polynomial.  Using ‘numel (a) - 1’ alone reports zero for
     every FIR filter, whose denominator is the scalar 1.

     Note that this is the order actually realized by the coefficients, which
     may exceed the order requested in the GUI: ‘dsp_compute_filter’ bumps
     odd-order FIR high-pass and band-stop designs up by one so they stay
     realizable.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
Return the realized order of the digital filter with numerator B and denomina...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 16
dsp_freq_axis_hz


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 818
 -- Function File: [HZ, LABEL] = dsp_freq_axis_hz ()
 -- Function File: [HZ, LABEL] = dsp_freq_axis_hz (NEW_VAL)
     Query or set the tool-wide frequency-axis unit mode.

     When HZ is false (the default) frequency axes are labelled in normalized
     radians per sample, 0 to \pi.  When true they are labelled in absolute
     frequency, 0 to Fs/2 Hz.  The flag is stored as appdata on the root object
     so every dsppack window (main screen, detailed analysis) shares the same
     mode; it is applied by ‘dsp_freq_xticks’, which falls back to \pi units for
     axes that have no sampling frequency associated with them (e.g.  the
     compare window, whose two filters may use different sampling rates).

     LABEL is the matching caption for the toggle buttons, describing the mode
     currently shown.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 52
Query or set the tool-wide frequency-axis unit mode.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 14
dsp_freq_ticks


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 1222
 -- Function File: dsp_freq_ticks ()
 -- Function File: dsp_freq_ticks (AX)
 -- Function File: dsp_freq_ticks (AX, FS)
 -- Function File: dsp_freq_ticks (AX, FS, DIM)
     Relabel a frequency axis of AX (default ‘gca’) according to the tool-wide
     unit mode (‘dsp_freq_axis_hz’).

     DIM selects which axis to relabel: ‘"x"’ (the default, used by every
     response plot) or ‘"y"’ (used by the audio demo's spectrograms, whose
     frequency runs vertically).

     Frequency data is plotted in \times\pi units (range [0, 1], i.e.  w/\pi)
     and is never rescaled - only the tick positions and labels change:

        • Normalized mode (default): ticks at 0, \pi/4, \pi/2, 3\pi/4, \pi with
          a matching \omega (rad/sample) label.
        • Hz mode: ticks at round Hz values (1/2/5 steps) between 0 and the
          Nyquist frequency FS/2, labelled in Hz (or kHz when Nyquist is at
          least 1 kHz), each placed at its normalized position f/(Fs/2).

     Hz mode only applies when a valid FS is supplied; callers that omit it
     (compare window, P/Z preview) always get the normalized labels regardless
     of the mode toggle.

     See also: dsp_freq_xticks, dsp_freq_axis_hz.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 84
Relabel a frequency axis of AX (default ‘gca’) according to the tool-wide uni...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 15
dsp_freq_xticks


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 412
 -- Function File: dsp_freq_xticks ()
 -- Function File: dsp_freq_xticks (AX)
 -- Function File: dsp_freq_xticks (AX, FS)
     Relabel the frequency x-axis of AX (default ‘gca’) according to the
     tool-wide unit mode (‘dsp_freq_axis_hz’).

     Thin wrapper over ‘dsp_freq_ticks (AX, FS, "x")’; see that function for the
     tick placement rules.

     See also: dsp_freq_ticks, dsp_freq_axis_hz.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 84
Relabel the frequency x-axis of AX (default ‘gca’) according to the tool-wide...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 19
dsp_generate_report


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 185
 -- Function File: dsp_generate_report (H)
     Generate a self-contained HTML report of the current filter design with
     specifications, stability analysis, plots, and coefficients.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
Generate a self-contained HTML report of the current filter design with
speci...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 17
dsp_load_callback


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 340
 -- Function File: dsp_load_callback (H)
     Load a filter design from a ‘.fil’ file, restore UI fields, and replot.

     Designs written before the FIR method list gained "Rectangular Window"
     carry no ‘format’ field; their FIR ‘topo_idx’ is shifted up by one on load
     so the method they named is the method selected.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 79
Load a filter design from a ‘.fil’ file, restore UI fields, and replot.

  



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 14
dsp_new_window


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 934
 -- Function File: FIG = dsp_new_window (NAME)
     Create a standard dsppack application window and return its handle.

     The figure is sized to the screen (capped at 1920x1080), centred, fixed
     (non-resizable), and has no menubar or default number-title.  Every dsppack
     window is created through this helper so their look and behaviour stay
     consistent, and so each one carries the ‘"dsppack_window"’ tag that lets
     ‘dsppack_launch’'s EXIT button close only this tool's own figures (leaving
     unrelated Octave figures untouched).

     Windows are deliberately non-resizable: the interactive click-to-place
     tools (‘fda_pz_editor’, ‘pz_tool’) hit-test clicks against the figure
     geometry, which a resizable native window reports inconsistently, and
     Octave's qt toolkit applies native hover styling to resizable windows that
     can render the coloured control buttons unreadable.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 67
Create a standard dsppack application window and return its handle.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 17
dsp_pad_flat_ylim


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 609
 -- Function File: dsp_pad_flat_ylim (AX, Y)
 -- Function File: dsp_pad_flat_ylim (AX, Y, PAD)
     Give AX a readable y-range when the data Y is constant or very nearly so.

     A linear-phase FIR filter has exactly constant group delay, which leaves
     the automatic y-limits degenerate: the curve is pinned to an edge of the
     box and every tick label rounds to the same number, so the axis reads ‘24
     24 24 24’.  This centres such a series in its box with a sensible margin
     (PAD, default 1 unit, or 5%% of the level when that is larger).

     Data with a real spread is left untouched.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 73
Give AX a readable y-range when the data Y is constant or very nearly so.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 11
dsp_plot_pz


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 1298
 -- Function File: dsp_plot_pz (AX, B, A)
 -- Function File: dsp_plot_pz (AX, B, A, STAB)
 -- Function File: dsp_plot_pz (AX, B, A, STAB, SHOW_LEGEND)
     Draw a ‘zplane’-style pole-zero diagram of the filter B/A on the axes AX.
     Used by the detailed analysis window and by the HTML report so the two
     always agree.

     Two things distinguish this from plotting ‘roots (b)’ and ‘roots (a)’
     directly:

        • Both polynomials are padded with roots at the origin up to the filter
          order, so an FIR filter shows the N poles it has at z = 0 (its
          denominator is the scalar 1, whose root set is empty) and an all-pole
          IIR shows its origin zeros.
        • Coincident roots are drawn as a single marker annotated with their
          occurrence number, rather than as markers stacked on top of each
          other.

     STAB is a struct from ‘dsp_check_stability’ (recomputed when omitted); it
     supplies the maximum-pole-radius circle.  SHOW_LEGEND defaults to true.

     Returns the legend handle (empty when SHOW_LEGEND is false) so a caller can
     reposition it - the equal-aspect plot is often small, and an in-axes legend
     covers a quadrant of it.

     See also: dsp_check_stability, dsp_filter_order, dsp_draw_zplane.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 81
Draw a ‘zplane’-style pole-zero diagram of the filter B/A on the axes AX.  Us



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 17
dsp_plot_response


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 161
 -- Function File: dsp_plot_response (AX_MAG, AX_PHASE, B, A, FS)
     Plot the magnitude and phase responses of a digital filter on the given
     axes handles.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
Plot the magnitude and phase responses of a digital filter on the given axes
...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 17
dsp_result_window


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 68
undocumented function: [] = dsp_result_window (parent_fig, b, a, Fs)


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 68
undocumented function: [] = dsp_result_window (parent_fig, b, a, Fs)



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 17
dsp_save_callback


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 397
 -- Function File: dsp_save_callback (H)
     Save the current filter design (parameters and coefficients) to a ‘.fil’
     file.

     The payload is written with Octave's own ‘save’, which uses its text format
     regardless of the file name.  Earlier releases named these files ‘.mat’
     even though they were never in MATLAB's MAT format; ‘.fil’ removes that
     ambiguity.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 84
Save the current filter design (parameters and coefficients) to a ‘.fil’ file...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 14
dsp_topo_names


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 394
 -- Function File: NAMES = dsp_topo_names (ARCH_IDX)
     Return the topology / method names offered for a given architecture as a
     cell array of strings, in the order used by the ‘topo_idx’ argument of
     ‘dsp_compute_filter’.

     ARCH_IDX is 1 for IIR and 2 for FIR. Every window that populates the
     Topology / Method popup uses this function, so the list is defined once.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
Return the topology / method names offered for a given architecture as a cell...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 20
dsp_update_stability


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 183
 -- Function File: dsp_update_stability (TXT_HANDLE, B, A)
     Run a BIBO stability check and update the given text UI control with the
     result (green for stable, red otherwise).


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
Run a BIBO stability check and update the given text UI control with the resu...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 14
dsppack_launch


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 91
 -- Function File: dsppack_launch ()
     Launches the Filter Design and Analysis Tool GUI.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 49
Launches the Filter Design and Analysis Tool GUI.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 15
dsppack_version


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 560
 -- Function File: V = dsppack_version ()
     Return the dsppack version string (e.g.  ‘"1.2.0"’).

     The value is read from the ‘Version:’ line of the package ‘DESCRIPTION’
     file, so anything that stamps a version into its output (saved designs,
     reports) stays in step with the package itself.  Both layouts are searched:
     ‘packinfo/DESCRIPTION’ beside the installed functions, and ‘../DESCRIPTION’
     when running straight from a source checkout.  If neither can be read the
     compiled-in fallback below is returned.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 60
Return the dsppack version string (e.g.  ‘"1.2.0"’).

  



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 13
fda_pz_editor


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 340
 -- Function File: fda_pz_editor (MAIN_FIG, FS)
     Interactive Z-Plane pole-zero editor.  Places poles and zeros by typing
     magnitude (r) and angle (deg) into the Manual Entry panel.  Enforces
     complex-conjugate symmetry so the resulting filter has real coefficients,
     then submits the design back to the main FDA Tool window.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 37
Interactive Z-Plane pole-zero editor.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 7
pz_tool


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 237
 -- Function File: pz_tool ()
     Interactive Pole-Zero placement tool with live magnitude frequency
     response.  Click on the Z-plane to place poles or zeros.  Complex
     conjugates are placed automatically for any off-axis click.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 76
Interactive Pole-Zero placement tool with live magnitude frequency response.





