Constraint

class fird.constraint.CoefficientBoundConstraint(upper: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, lower: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | 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]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, period: int = 1) → None

Add constraint to an FIR filter optimization problem.

Parameters:

problemLpProblem

Problem instance to add constraint to.

coefficientsdict[int, pulp.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.

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]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, period: int = 1) → None

Add constraint to an FIR filter optimization problem.

Parameters:

problemLpProblem

Problem instance to add constraint to.

coefficientsdict[int, pulp.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.

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]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, period: int = 1) → None

Add constraint to an FIR filter optimization problem.

Parameters:

problemLpProblem

Problem instance to add constraint to.

coefficientsdict[int, pulp.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.

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

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]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, period: int = True) → None

Add constraint to an FIR filter optimization problem.

Parameters:

problemLpProblem

Problem instance to add constraint to.

coefficientsdict[int, pulp.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.

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, upper: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, lower: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None)

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]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, period: int = 1) → None

Add constraint to an FIR filter optimization problem.

Parameters:

problemLpProblem

Problem instance to add constraint to.

coefficientsdict[int, pulp.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.

class fird.constraint.NyquistConstraint(m: int)

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.

Parameters:

mint

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]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, period: int = 1) → None

Add constraint to an FIR filter optimization problem.

Parameters:

problemLpProblem

Problem instance to add constraint to.

coefficientsdict[int, pulp.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.

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.