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
widthandsteepnessof the curve independently. 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 max_power_barrier with power = 1 (shown above):
| * | ** - (x_nominal, error_nominal^2) | * | ** <- x^(2*power) is the shape of the cost 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.
- Return type:
- 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. Seemax_power_barrier()for more details.
- 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:
- 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. Seemin_power_barrier()for more details.
- symmetric_power_barrier(x, x_nominal, error_nominal, dist_zero_to_nominal, power)[source]#
A symmetric barrier centered 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):
* | * ** | ** - (x_nominal, 1/2 * error_nominal^2) * | * ** | ** <- x^(2*power) is the shape of the cost 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) – 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:
- 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 ** | ** ---------------------------------------*****************--------- dist_zero_to_nominal |<->| | |<->| dist_zero_to_nominal
- 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:
- 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. Seemin_max_power_barrier()for more details.
- 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 visualize 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: