ladybug.rootfinding module¶

Utilities for finding roots of continuous functions.

ladybug.rootfinding.bisect(a, b, fn, epsilon, target=0)[source]¶

Solve for a root using the simplest root-finding algorithm.

It is extremely reliable. However, it converges slowly for this reason, it is recommended that this only be used after the secant() method has returned None.

Parameters:

a – A lower guess of the value you are tying to find.
b – A higher guess of the value you are tying to find.
fn –
A function representing the relationship between the value you are trying to find and the target condition you are trying to satisfy. It should typically be structured in the following way:
```
def fn(value_trying_to_find):
    funct(value_trying_to_find) - target_desired_from_funct
```
…but the subtraction should be switched if value_trying_to_find has a negative relationship with the funct.
epsilon – The acceptable error in the target_desired_from_funct.
target – The target slope (typically 0 for a local minima or maxima).

Returns:

root – The value that gives the target_desired_from_funct.

References

[1] Wikipedia contributors. (2018, December 29). Root-finding algorithm. In Wikipedia, The Free Encyclopedia. Retrieved 18:16, December 30, 2018, from https://en.wikipedia.org/wiki/Root-finding_algorithm#Bisection_method

ladybug.rootfinding.secant(a, b, fn, epsilon)[source]¶

Solve for a root using one of the fastest root-finding algorithms.

The method calculates the slope of the function fn and this enables it to converge to a solution very fast. However, if started too far away from a root, the method may not converge (returning a None). For this reason, it is recommended that this function be used first in any guess-and-check workflow and, if it fails to find a root, the bisect() method should be used.

Parameters:

a – The lowest possible boundary of the value you are tying to find.
b – The highest possible boundary of the value you are tying to find.
fn –
A function representing the relationship between the value you are trying to find and the target condition you are trying to satisfy. It should typically be structured in the following way:
```
def fn(value_trying_to_find):
    funct(value_trying_to_find) - target_desired_from_funct
```
…but the subtraction should be switched if value_trying_to_find has a negative relationship with the funct.
epsilon – The acceptable error in the target_desired_from_funct.

Returns:

root – The value that gives the target_desired_from_funct in the sample above (aka. the value that returns 0 from the fn).

References

ladybug.rootfinding.secant_three_var(a, b, fn, epsilon, other_args)[source]¶

Solve the roots of a 3-variable function with one of the fastest algorithms.

Parameters:

a – A tuple with 3 numbers for the the lowest boundary of the roots.
b – A tuple with 3 numbers for the the highest boundary of the roots.
fn – A function for which roots are to be solved. That is, where the output of the function is a tuple of three zeros.
epsilon – The acceptable error in the resulting root.
other_args – Other input arguments for the fn other than the ones being adjusted to solve the root.

Returns:

root – a tuple of 3 values that return a vector of zeros from the fn.