# symforce.opt.barrier_functions module#

max_power_barrier(x, x_nominal, error_nominal, dist_zero_to_nominal, power, epsilon=0.0)[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:

```                    |              **
|             ** - (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.

• epsilon (float) – Used iff power is not an sf.Number

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:
Return type:

float

min_power_barrier(x, x_nominal, error_nominal, dist_zero_to_nominal, power, epsilon=0.0)[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.

• epsilon (float) –

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:
Return type:

float

symmetric_power_barrier(x, x_nominal, error_nominal, dist_zero_to_nominal, power, epsilon=0.0)[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.

• epsilon (float) –

Return type:

float

min_max_power_barrier(x, x_nominal_lower, x_nominal_upper, error_nominal, dist_zero_to_nominal, power, epsilon=0.0)[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.

• epsilon (float) –

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, epsilon=0.0)[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).

• epsilon (float) –

Return type:

float