symforce.opt.barrier_functions module¶
- max_power_barrier(x, x_nominal, error_nominal, dist_zero_to_nominal, power)[source]¶
A one-sided, non-symmetric scalar barrier function. The barrier passes through the points (x_nominal, error_nominal) and (x_nominal - dist_zero_to_nominal, 0) with a curve of the form x^power. The parameterization of the barrier by these variables is convenient because it allows setting a constant penalty for a nominal point, then adjusting the width and steepness of the curve independently. The barrier with power = 1 will look like:
Note that when applying the barrier function to a residual used in a least-squares problem, a power = 1 will lead to a quadratic cost in the optimization problem because the cost equals 1/2 * residual^2. For example:
Cost (1/2 * residual^2) when the residual is a max_power_barrier with power = 1 (shown above):
- Parameters:
x (
float
) – The point at which we want to evaluate the barrier function.x_nominal (
float
) – x-value of the point at which the error is equal to error_nominal.error_nominal (
float
) – Error returned when x equals x_nominal.dist_zero_to_nominal (
float
) – The distance from x_nominal to the region of zero error. Must be a positive number.power (
float
) – The power used to describe the curve of the error tails.
- Return type:
float
- max_linear_barrier(x, x_nominal, error_nominal, dist_zero_to_nominal)[source]¶
Applies “max_power_barrier” with power = 1. When applied to a residual of a least-squares problem, this produces a quadratic cost in the optimization problem because cost = 1/2 * residual^2. See “max_power_barrier” for more details.
- Parameters:
x (
float
) –x_nominal (
float
) –error_nominal (
float
) –dist_zero_to_nominal (
float
) –
- Return type:
float
- min_power_barrier(x, x_nominal, error_nominal, dist_zero_to_nominal, power)[source]¶
A one-sided, non-symmetric scalar barrier function. The barrier passes through the points (x_nominal, error_nominal) and (x_nominal + dist_zero_to_nominal, 0) with a curve of the form x^power. The barrier with power = 1 will look like:
** |
- (x_nominal, error_nominal) - ** |
** |
- x^power is the shape of the curve -> ** |
- ** |
** |
———******************———
dist_zero_to_nominal |<->| |
- Parameters:
x (
float
) – The point at which we want to evaluate the barrier function.x_nominal (
float
) – x-value of the point at which the error is equal to error_nominal.error_nominal (
float
) – Error returned when x equals x_nominal.dist_zero_to_nominal (
float
) – The distance from x_nominal to the region of zero error. Must be a positive number.power (
float
) – The power used to describe the curve of the error tails. Note that when applying the barrier function to a residual used in a least-squares problem, a power = 1 will lead to a quadratic cost in the optimization problem.
- Return type:
float
- min_linear_barrier(x, x_nominal, error_nominal, dist_zero_to_nominal)[source]¶
Applies “min_power_barrier” with power = 1. When applied to a residual of a least-squares problem, this produces a quadratic cost in the optimization problem because cost = 1/2 * residual^2. See “min_power_barrier” for more details.
- Parameters:
x (
float
) –x_nominal (
float
) –error_nominal (
float
) –dist_zero_to_nominal (
float
) –
- Return type:
float
- symmetric_power_barrier(x, x_nominal, error_nominal, dist_zero_to_nominal, power)[source]¶
A symmetric barrier cenetered around x = 0, meaning the error at -x is equal to the error at x. The barrier passes through the points (x_nominal, error_nominal) and (x_nominal - dist_zero_to_nominal, 0) with a curve of the form x^power. For example, the barrier with power = 1 will look like:
- ** | **
- ** | ** - (x_nominal, error_nominal) is a fixed point
- ** | **
- ** | ** <- x^power is the shape of the curve
- ** | **
** | **
- ———-*****************———
- |<-->| dist_zero_to_nominal is the distance from x_nominal to the point at which the error is zero
Note that when applying the barrier function to a residual used in a least-squares problem, a power = 1 will lead to a quadratic cost in the optimization problem because the cost equals 1/2 * residual^2. For example:
Cost (1/2 * residual^2) when the residual is a symmetric barrier with power = 1 (shown above):
- Parameters:
x (
float
) – The point at which we want to evaluate the barrier function.x_nominal (
float
) – x-value of the point at which the error is equal to error_nominal.error_nominal (
float
) – Error returned when x equals x_nominal.dist_zero_to_nominal (
float
) – Distance from x_nominal to the closest point at which the error is zero. Note that dist_zero_to_nominal must be less than x_nominal and greater than zero.power (
float
) – The power used to describe the curve of the error tails.
- Return type:
float
- min_max_power_barrier(x, x_nominal_lower, x_nominal_upper, error_nominal, dist_zero_to_nominal, power)[source]¶
A symmetric barrier centered between x_nominal_lower and x_nominal_upper. See symmetric_power_barrier for a detailed description of the barrier function. As an example, the barrier with power = 1 will look like:
- ** | **
** | **
- (x_nominal_lower, error_nominal) - ** | ** - (x_nominal_upper, error_nominal)
- ** | **
- ** | ** <- x^power is the shape of the curve
** | **
———-*************———
- Parameters:
x (
float
) – The point at which we want to evaluate the barrier function.x_nominal_lower (
float
) – x-value of the point at which the error is equal to error_nominal on the left-hand side of the barrier function.x_nominal_upper (
float
) – x-value of the point at which the error is equal to error_nominal on the right-hand side of the barrier function.error_nominal (
float
) – Error returned when x equals x_nominal_lower or x_nominal_upper.dist_zero_to_nominal (
float
) – The distance from either of the x_nominal points to the region of zero error. Must be less than half the distance between x_nominal_lower and x_nominal_upper, and must be greater than zero.power (
float
) – The power used to describe the curve of the error tails. Note that when applying the barrier function to a residual used in a least-squares problem, a power = 1 will lead to a quadratic cost in the optimization problem.
- Return type:
float
- min_max_linear_barrier(x, x_nominal_lower, x_nominal_upper, error_nominal, dist_zero_to_nominal)[source]¶
Applies “min_max_power_barrier” with power = 1. When applied to a residual of a least-squares problem, this produces a quadratic cost in the optimization problem because cost = 1/2 * residual^2. See “min_max_power_barrier” for more details.
- Parameters:
x (
float
) –x_nominal_lower (
float
) –x_nominal_upper (
float
) –error_nominal (
float
) –dist_zero_to_nominal (
float
) –
- Return type:
float
- min_max_centering_power_barrier(x, x_nominal_lower, x_nominal_upper, error_nominal, dist_zero_to_nominal, power, centering_scale)[source]¶
This barrier is the maximum of two power barriers which we call the “bounding” barrier and the “centering” barrier. Both barriers are centered between x_nominal_lower and x_nominal_upper. As an example, the barrier with power = 1 may look like:
- BARRIER (max of bounding and centering barriers):
- ** | **
- ** <-(x_nominal_lower, error_nominal) ** <-(x_nominal_upper, error_nominal)
- ** | **
- ** | **
- ** | **
- ** | ** <- x^power is the shape of upper/lower curve
** **
- ——————***——————-
It may be easier to vizualize the bounding and centering barriers independently:
- BOUNDING BARRIER:
- ** | **
- ** <-(x_nominal_lower, error_nominal) ** <-(x_nominal_upper, error_nominal)
- ** | **
- ** | **
- ** | ** <- x^power is the shape of the curve
- ** | **
** | **
- ——***************************——-
- |<-->| dist_zero_to_nominal
- CENTERING BARRIER:
- ** | **
** | **
- nominal_lower ^ ** | ** ^ nominal_upper
- ** | **
** ** <- x^power is the shape of the curve
- ——————***——————-
- ^-((x_nominal_lower + x_nominal_upper) / 2, 0)
- where:
nominal_lower = (x_nominal_lower, centering_scale * error_nominal) nominal_upper = (x_nominal_upper, centering_scale * error_nominal)
and the only point with zero error is the midpoint of x_nominal_lower and x_nominal_upper.
- Parameters:
x (
float
) – The point at which we want to evaluate the barrier function.x_nominal_lower (
float
) – x-value of the point at which the error is equal to error_nominal on the left-hand side of the barrier function.x_nominal_upper (
float
) – x-value of the point at which the error is equal to error_nominal on the right-hand side of the barrier function.error_nominal (
float
) – Error returned when x equals x_nominal_lower or x_nominal_upper.dist_zero_to_nominal (
float
) – Used with the “bounding barrier” to define the distance from either of the x_nominal points to the region of zero error. Must be less than half the distance between x_nominal_lower and x_nominal_upper, and must be greater than zero.power (
float
) – The power used to describe the curve of the error tails. Note that when applying the barrier function to a residual used in a least-squares problem, a power = 1 will lead to a quadratic cost in the optimization problem.centering_scale (
float
) – Used to define the shape of the “centering barrier”. Must be between zero and one. The centering barrier passes through (x_nominal_lower, centering_scale * error_nominal), ((x_nominal_lower + x_nominal_upper) / 2, 0), and (x_nominal_upper, centering_scale * error_nominal).
- Return type:
float