Constraint

class fird.constraint.CoefficientBoundConstraint(upper: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | int | float | None = None, lower: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | int | float | None = None)

Bases: Constraint

Constraint that bounds coefficient values.

If an array is provided, it must be of same length as the filter that will be designed. Use float(inf) or float(nan) in an array for values that should not be bounded.

Parameters:

upper1D-array, int, or float, optional

Upper bound for coefficient values.

lower1D-array, int, or float, optional

Lower bound for coefficient values.

add_to_problem(problem: LpProblem, coefficients: dict[int, LpVariable], *, odd_order: bool = True, fractional_bits: int | None = None, even_symmetry: bool = True, cascade_filter: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None, period: int = 1, Linf_coefficients: dict[int, LpVariable] | None = None, L1_coefficients: dict[int, LpVariable] | None = None) → None

Add constraint to an FIR filter optimization problem.

Parameters:

problemLpProblem

Problem instance to add constraint to.

coefficientsdict of int, LpVariable

Coefficient variables.

odd_orderbool, default: True

If the filter order is odd or even.

fractional_bitsint, optional

Number of fractional bits for fixed-point coefficients. If not provided, continuous (floating-point) coefficients are used.

even_symmetrybool, default: True

If the filter to be designed is of odd or even symmetry.

cascade_filter1D array, optional

The optional filter in cascade with the designed.

periodint, default: 1

The period of the designed filter in relation to the specification.

Linf_coefficientsdict of int, LpVariable, optional

Binary variables saying if a coefficient is non-zero or not.

L1_coefficientsdict of int, LpVariable, optional

Variables with absolute value of the coefficients.

class fird.constraint.Constraint

Bases: ABC

Abstract base class for FIR filter design constraint.

abstractmethod add_to_problem(problem: LpProblem, coefficients: dict[int, LpVariable], *, odd_order: bool = True, fractional_bits: int | None = None, even_symmetry: bool = True, cascade_filter: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None, period: int = 1, Linf_coefficients: dict[int, LpVariable] | None = None, L1_coefficients: dict[int, LpVariable] | None = None) → None

Add constraint to an FIR filter optimization problem.

Parameters:

problemLpProblem

Problem instance to add constraint to.

coefficientsdict of int, LpVariable

Coefficient variables.

odd_orderbool, default: True

If the filter order is odd or even.

fractional_bitsint, optional

Number of fractional bits for fixed-point coefficients. If not provided, continuous (floating-point) coefficients are used.

even_symmetrybool, default: True

If the filter to be designed is of odd or even symmetry.

cascade_filter1D array, optional

The optional filter in cascade with the designed.

periodint, default: 1

The period of the designed filter in relation to the specification.

Linf_coefficientsdict of int, LpVariable, optional

Binary variables saying if a coefficient is non-zero or not.

L1_coefficientsdict of int, LpVariable, optional

Variables with absolute value of the coefficients.

to_objective() → Objective

Convert constraint to objective.

Returns:

Objective

Raises:

TypeError

Not all constraints can be converted to objectives.

class fird.constraint.FunctionLinearConstraint(bounds: Sequence[float], function: Callable[[float], tuple[float, float]] | Callable[[float], float], points: Sequence[int] | int | None = None)

Bases: LinearConstraint

plot(ax: Axes, frequency_scale: float = 3.141592653589793, zero_phase: bool = False, desired_line: str | None = 'g', deviation_line: str | None = 'r', plot_db: bool = False) → None

Plot constraint in Matplotlib Axes.

Parameters:

axAxes

The Axes to plot in.

frequency_scalefloat, default: pi

Multiply the frequency values (normalized 0 to 1) when plotting.

zero_phasebool, default: False

If plotting the zero-phase magnitude response, i.e., the magnitude can take on negative values, set this to True.

desired_linestr, default: ‘g’

Matplotlib line definition string for the desired values. Set to None to not plot desired line.

deviation_linestr, default: ‘r’

Matplotlib line definition string for the deviation values. Set to None to not plot deviation line.

plot_dbbool, optional

If True, plot \(20\log_{10}\) of the constraint magnitudes.

class fird.constraint.L1CoefficientsConstraint(l1bound: float)

Bases: Constraint

add_to_problem(problem: LpProblem, coefficients: dict[int, LpVariable], *, odd_order: bool = True, fractional_bits: int | None = None, even_symmetry: bool = True, cascade_filter: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None, period: int = 1, Linf_coefficients: dict[int, LpVariable] | None = None, L1_coefficients: dict[int, LpVariable] | None = None) → None

Add constraint to an FIR filter optimization problem.

Parameters:

problemLpProblem

Problem instance to add constraint to.

coefficientsdict of int, LpVariable

Coefficient variables.

odd_orderbool, default: True

If the filter order is odd or even.

fractional_bitsint, optional

Number of fractional bits for fixed-point coefficients. If not provided, continuous (floating-point) coefficients are used.

even_symmetrybool, default: True

If the filter to be designed is of odd or even symmetry.

cascade_filter1D array, optional

The optional filter in cascade with the designed.

periodint, default: 1

The period of the designed filter in relation to the specification.

Linf_coefficientsdict of int, LpVariable, optional

Binary variables saying if a coefficient is non-zero or not.

L1_coefficientsdict of int, LpVariable, optional

Variables with absolute value of the coefficients.

to_objective() → Objective

Convert constraint to objective.

Returns:

Objective

Raises:

TypeError

Not all constraints can be converted to objectives.

class fird.constraint.LinearConstraint(frequencies: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], desired_values: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], deviations: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str])

Bases: Constraint

Base class for any linear constraint.

A linear constraint is on the form

\[\left|H_R(\omega) - D(\omega)\right| \leq \delta(\omega)\]

where \(H_R(\omega)\) is the zero-phase magnitude response. This can be rewritten as

\[-\delta(\omega) \leq H_R(\omega) - D(\omega) \leq \delta(\omega)\]

The values are represented as arrays with frequencies \(= \omega\), desired_values \(= D(\omega)\), and deviations \(= \delta(\omega)\).

Parameters:

frequenciesnpt.ArrayLike

Array of frequencies to form constraints for.

desired_valuesnpt.ArrayLike

Array of desired values at frequencies.

deviationsnpt.ArrayLike

Array of allowed deviations (ripples) at frequencies.

See also

PiecewiseLinearConstraint

FunctionLinearConstraint

add_to_problem(problem: LpProblem, coefficients: dict[int, LpVariable], *, odd_order: bool = True, fractional_bits: int | None = None, even_symmetry: bool = True, cascade_filter: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None, period: int = True, Linf_coefficients: dict[int, LpVariable] | None = None, L1_coefficients: dict[int, LpVariable] | None = None) → None

Add constraint to an FIR filter optimization problem.

Parameters:

problemLpProblem

Problem instance to add constraint to.

coefficientsdict of int, LpVariable

Coefficient variables.

odd_orderbool, default: True

If the filter order is odd or even.

fractional_bitsint, optional

Number of fractional bits for fixed-point coefficients. If not provided, continuous (floating-point) coefficients are used.

even_symmetrybool, default: True

If the filter to be designed is of odd or even symmetry.

cascade_filter1D array, optional

The optional filter in cascade with the designed.

periodint, default: 1

The period of the designed filter in relation to the specification.

Linf_coefficientsdict of int, LpVariable, optional

Binary variables saying if a coefficient is non-zero or not.

L1_coefficientsdict of int, LpVariable, optional

Variables with absolute value of the coefficients.

plot(ax: Axes, frequency_scale: float = 3.141592653589793, zero_phase: bool = False, desired_line: str | None = 'g', deviation_line: str | None = 'r', plot_db: bool = False) → None

Plot constraint in Matplotlib Axes.

Parameters:

axAxes

The Axes to plot in.

frequency_scalefloat, default: pi

Multiply the frequency values (normalized 0 to 1) when plotting.

zero_phasebool, default: False

If plotting the zero-phase magnitude response, i.e., the magnitude can take on negative values, set this to True.

desired_linestr, default: ‘g’

Matplotlib line definition string for the desired values. Set to None to not plot desired line.

deviation_linestr, default: ‘r’

Matplotlib line definition string for the deviation values. Set to None to not plot deviation line.

plot_dbbool, optional

If True, plot \(20\log_{10}\) of the constraint magnitudes.

to_objective() → LinearObjective

Convert constraint to objective.

Returns:

Objective

Raises:

TypeError

Not all constraints can be converted to objectives.

class fird.constraint.MaxNonzeroCoefficientsConstraint(max_nonzero_coefficients: int)

Bases: Constraint

add_to_problem(problem: LpProblem, coefficients: dict[int, LpVariable], *, odd_order: bool = True, fractional_bits: int | None = None, even_symmetry: bool = True, cascade_filter: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None, period: int = 1, Linf_coefficients: dict[int, LpVariable] | None = None, L1_coefficients: dict[int, LpVariable] | None = None) → None

Add constraint to an FIR filter optimization problem.

Parameters:

problemLpProblem

Problem instance to add constraint to.

coefficientsdict of int, LpVariable

Coefficient variables.

odd_orderbool, default: True

If the filter order is odd or even.

fractional_bitsint, optional

Number of fractional bits for fixed-point coefficients. If not provided, continuous (floating-point) coefficients are used.

even_symmetrybool, default: True

If the filter to be designed is of odd or even symmetry.

cascade_filter1D array, optional

The optional filter in cascade with the designed.

periodint, default: 1

The period of the designed filter in relation to the specification.

Linf_coefficientsdict of int, LpVariable, optional

Binary variables saying if a coefficient is non-zero or not.

L1_coefficientsdict of int, LpVariable, optional

Variables with absolute value of the coefficients.

to_objective() → Objective

Convert constraint to objective.

Returns:

Objective

Raises:

TypeError

Not all constraints can be converted to objectives.

class fird.constraint.NyquistConstraint(m: int, interpolator: bool = False)

Bases: CoefficientBoundConstraint

Nyquist (Mth-band) filter constraint.

In a Nyquist filter, the middle tap is of magnitude 1/m and every m-th coefficient is 0.

Note

For fixed-point designs, the middle tap is rounded to the nearest fixed-point value. Hence, for non-power-of-two m, the actual value may deviate slightly from 1/m.

Parameters:

mint

The Nyquist factor.

interpolatorbool, default: False

Scale the coefficients with m to get unity gain for the polyphase branches.

add_to_problem(problem: LpProblem, coefficients: dict[int, LpVariable], *, odd_order: bool = True, fractional_bits: int | None = None, even_symmetry: bool = True, cascade_filter: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None, period: int = 1, Linf_coefficients: dict[int, LpVariable] | None = None, L1_coefficients: dict[int, LpVariable] | None = None) → None

Add constraint to an FIR filter optimization problem.

Parameters:

problemLpProblem

Problem instance to add constraint to.

coefficientsdict of int, LpVariable

Coefficient variables.

odd_orderbool, default: True

If the filter order is odd or even.

fractional_bitsint, optional

Number of fractional bits for fixed-point coefficients. If not provided, continuous (floating-point) coefficients are used.

even_symmetrybool, default: True

If the filter to be designed is of odd or even symmetry.

cascade_filter1D array, optional

The optional filter in cascade with the designed.

periodint, default: 1

The period of the designed filter in relation to the specification.

Linf_coefficientsdict of int, LpVariable, optional

Binary variables saying if a coefficient is non-zero or not.

L1_coefficientsdict of int, LpVariable, optional

Variables with absolute value of the coefficients.

class fird.constraint.PiecewiseLinearConstraint(bounds: Sequence[float], desired_values: Sequence[float], deviations: Sequence[float], points: Sequence[int] | int | None = None)

Bases: LinearConstraint

plot(ax: Axes, frequency_scale: float = 3.141592653589793, zero_phase: bool = False, desired_line: str | None = 'g', deviation_line: str | None = 'r', plot_db: bool = False) → None

Plot constraint in Matplotlib Axes.

Parameters:

axAxes

The Axes to plot in.

frequency_scalefloat, default: pi

Multiply the frequency values (normalized 0 to 1) when plotting.

zero_phasebool, default: False

If plotting the zero-phase magnitude response, i.e., the magnitude can take on negative values, set this to True.

desired_linestr, default: ‘g’

Matplotlib line definition string for the desired values. Set to None to not plot desired line.

deviation_linestr, default: ‘r’

Matplotlib line definition string for the deviation values. Set to None to not plot deviation line.

plot_dbbool, optional

If True, plot \(20\log_{10}\) of the constraint magnitudes.