Maths functions
===============

The following Maths Functions come bundled with RiskScape for use in your function.

.. _builtin_maths_functions:

## Built-in maths functions

RiskScape comes with a set of default functions that are useful for doing mathematics
in the context of RiskScape and Risk Analysis.  They are used like any other RiskScape function.
For example, to round a floating point number, you can use the `round` function like `round(-34.23)`.

Where possible, RiskScape makes use of maths packages that are part of the Java language.
These packages are widely used and are proven to produce reliable mathematical results.
For example, the `square_root()` RiskScape function is just a simple 'wrapper' for the
Java `Math.sqrt()` function.

More specific help for all these built-in functions is available from RiskScape's built-in help.
From the command line, you can use `riskscape function list` to see what functions are
available, the arguments each function takes, and what they return.
To list the maths functions available in RiskScape, run `riskscape function list --category maths`.

`abs`
  Gives the absolute value of a number

`ceil`
  Round number up to the closest integer

`exp`
  Returns Euler's number (e) raised to the power of the value given. The inverse of log()

`float`
  Convert input to a floating point number

`floor`
  Round number down to the closest integer

`int`
  Convert input to a integer number

`log`
  Return the logarithm of a number for a particular base, defaulting to natural log if none given

`log10`
  Returns the base-10 logarithm of the given value

`lognorm_cdf`
  Cumulative probability distribution function from a log-normal curve. Where shape is σ (standard deviation) and scale is μ (mean), both as the log of the distribution.

`lognorm_pdf`
  Probability Density Function (PDF) for a given point in a normal distribution.  Where shape is σ (standard deviation) and scale is μ (mean), both as the log of the distribution.

`max`
  Returns the greater of two values given

`min`
  Returns the smaller of two values given

`norm_cdf`
  Cumulative probability distribution function from a normal curve

`norm_pdf`
  Probability Density Function (PDF) for a given point in a normal distribution

`polynomial`
  Computes a polynomial expression, denoted by the set of coefficients 'c' (starting at x⁰, x, x², etc)

`pow`
  Raise a number by a specific power

`random_choice`
  Picks an item from the list at random, or with an optional weighted probability

`random_norm`
  Returns a random number from the given normal distribution

`random_uniform`
  Returns a random number within the range [start, stop]

`round`
  Round number to the closest integer

`square_root`
  Get the square root of the given number

## Jython discrete functions

.. note::
    The following sections describe using RiskScape-based code from within a *Jython* function.
    Most Python users will probably find it simpler to setup RiskScape to use :ref:`cpython-impl`
    and use standard Python maths packages instead.

A discrete function can be constructed from points, constants and other
functions, to form a single function for use with risk analysis.

### Using points

The simplest use of a discrete function is to join up a series of points to
create a continuous sequence of lines between them.

``` python
from nz.org.riskscape.engine.function import DiscreteFunction

ID = 'joined-points'
DESCRIPTION = 'Demonstrates a function built by connecting points to form a series of linear functions'

FUNCTION = DiscreteFunction.builder() \
           .addPoint(-1, 4) \
           .addPoint(1, 6) \
           .addPoint(4, 8) \
           .addPoint(10, 10) \
           .withLinearInterpolation() \
           .build()
```

### Constants

As well as adding a point, a constant value can be added for a range:

```none
# will return 0.45 when 0 <= x <= 10
DiscreteFunction.builder().addConstant(0, 10, 0.45)
```

### Joining functions

Arbitrary RiskScape functions can be joined up to form a single function.  Each function is
added along with the range for which it's applicable:

``` python
from nz.org.riskscape.engine.function import DiscreteFunction, Maths

ID = 'joined-polynomials'
DESCRIPTION = 'Demonstrates a function built by connecting polynomials'


quadratic = Maths.newPolynomial(0, 8, 0.25)
cubic = Maths.newPolynomial(10, 0, 4, 0.5)

FUNCTION = DiscreteFunction.builder() \
           .addFunction(-10, -5, cubic) \
           .addFunction(40, 1000, polynomial) \
           .withLinearInterpolation() \
           .build()
```

### Ranges

By default, a discrete function will 'close' any upper bound on a range that
isn't connected to a higher range.  For example, adding the range
`addFunction(0, 10, somePolynomial)` will make that polynomial
apply when `0 <= x <= 10`.  However, if a function is added from 10 onwards,
then `somePolynomial` applies when `0 <= x < 10`.

This closing behaviour can be disabled by calling `.withoutUpperBoundClosing`
on the function builder.