# FinanceCore API Reference

`FinanceCore.Cashflow`

`FinanceCore.Composite`

`FinanceCore.Continuous`

`FinanceCore.Continuous`

`FinanceCore.Periodic`

`FinanceCore.Periodic`

`FinanceCore.Quote`

`FinanceCore.Rate`

`FinanceCore.Timepoint`

`FinanceCore.accumulation`

`FinanceCore.amount`

`FinanceCore.discount`

`FinanceCore.forward`

`FinanceCore.internal_rate_of_return`

`FinanceCore.irr`

`FinanceCore.present_value`

`FinanceCore.present_value`

`FinanceCore.rate`

`FinanceCore.timepoint`

## Exported API

`FinanceCore.Cashflow`

— Type`Cashflow(amount,time)`

A `Cahflow{A,B}`

is a contract that pays an `amount`

at `time`

.

Cashflows can be:

- negated with the unary
`-`

operator. - added/subtracted together but note that the
`time`

must be`isapprox`

equal. - multiplied/divided by a scalar.

Supertype Hierarchy ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡

`Cashflow{A<:Real, B<:Timepoint} <: FinanceCore.AbstractContract <: Any`

`FinanceCore.Composite`

— Type`Composite(A,B)`

Summary ≡≡≡≡≡≡≡≡≡

`struct Composite{A, B}`

A `Composite{A,B}`

is a contract that is composed of two other contracts of type `A`

and type `B`

. The maturity of the composite is the maximum of the maturities of the two components.

It is used to assemble arbitrarily complex contracts from simpler ones.

Fields ≡≡≡≡≡≡≡≡

```
a :: A
b :: B
```

Supertype Hierarchy ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡

`Composite{A, B} <: FinanceCore.AbstractContract <: Any`

`FinanceCore.Continuous`

— Type`Continuous()`

A type representing continuous interest compounding frequency.

**Examples**

```
julia> Rate(0.01,Continuous())
Rate(0.01, Continuous())
```

See also: `Periodic`

`FinanceCore.Continuous`

— Method```
julia> Continuous(0.01)
Rate(0.01, Continuous())
```

See also: `Periodic`

`FinanceCore.Periodic`

— Type`Periodic(frequency)`

A type representing periodic interest compounding with the given frequency.

`frequency`

will be converted to an `Integer`

, and will round up to 8 decimal places (otherwise will throw an `InexactError`

).

**Examples**

Creating a semi-annual bond equivalent yield:

```
julia> Rate(0.01,Periodic(2))
Rate(0.01, Periodic(2))
```

See also: `Continuous`

`FinanceCore.Periodic`

— Method`Periodic(rate,frequency)`

A convenience constructor for Rate(rate,Periodic(frequency)).

**Examples**

Creating a semi-annual bond equivalent yield:

```
julia> Periodic(0.01,2)
Rate(0.01, Periodic(2))
```

See also: `Continuous`

`FinanceCore.Quote`

— Type`Quote(price,instrument)`

The `price`

(`<:Real`

) is the observed value , and the `instrument`

is the instrument/contract that the price is for.

This can be used, e.g., to calibrate a valuation model to prices for the given instruments - see FinanceModels.jl for more details.

`FinanceCore.Rate`

— Method```
Rate(rate[,frequency=1])
Rate(rate,frequency::Frequency)
```

Rate is a type that encapsulates an interest `rate`

along with its compounding `frequency`

.

Periodic rates can be constructed via `Rate(rate,frequency)`

or `Rate(rate,Periodic(frequency))`

. If not given a second argument, `Rate(rate)`

is equivalent to `Rate(rate,Periodic(1))`

.

Continuous rates can be constructed via `Rate(rate, Inf)`

or `Rate(rate,Continuous())`

.

**Examples**

```
julia> Rate(0.01,Continuous())
Rate(0.01, Continuous())
julia> Continuous(0.01)
Rate(0.01, Continuous())
julia> Continuous()(0.01)
Rate(0.01, Continuous())
julia> Rate(0.01,Periodic(2))
Rate(0.01, Periodic(2))
julia> Periodic(0.01,2)
Rate(0.01, Periodic(2))
julia> Periodic(2)(0.01)
Rate(0.01, Periodic(2))
julia> Rate(0.01)
Rate(0.01, Periodic(1))
julia> Rate(0.01,2)
Rate(0.01, Periodic(2))
julia> Rate(0.01,Periodic(4))
Rate(0.01, Periodic(4))
julia> Rate(0.01,Inf)
Rate(0.01, Continuous())
```

`FinanceCore.amount`

— Method`amount(x)`

If is an object with an amount component (e.g. a `Cashflow`

), will retrun that amount component, otherwise just `x`

.

**Examples**

```
julia> FinanceCore.amount(Cashflow(1.,3.))
1.0
julia> FinanceCore.amount(1.)
1.0
```

`FinanceCore.internal_rate_of_return`

— Method```
internal_rate_of_return(cashflows::vector)::Rate
internal_rate_of_return(cashflows::Vector, timepoints::Vector)::Rate
```

Calculate the internal*rate*of_return with given timepoints. If no timepoints given, will assume that a series of equally spaced cashflows, assuming the first cashflow occurring at time zero and subsequent elements at time 1, 2, 3, ..., n.

Returns a Rate type with periodic compounding once per period (e.g. annual effective if the `timepoints`

given represent years). Get the scalar rate by calling `Yields.rate()`

on the result.

**Example**

```
julia> internal_rate_of_return([-100,110],[0,1]) # e.g. cashflows at time 0 and 1
0.10000000001652906
julia> internal_rate_of_return([-100,110]) # implied the same as above
0.10000000001652906
```

**Solver notes**

Will try to return a root within the range [-2,2]. If the fast solver does not find one matching this condition, then a more robust search will be performed over the [.99,2] range.

The solution returned will be in the range [-2,2], but may not be the one nearest zero. For a slightly slower, but more robust version, call `ActuaryUtilities.irr_robust(cashflows,timepoints)`

directly.

`FinanceCore.irr`

— Function```
irr(cashflows::vector)
irr(cashflows::Vector, timepoints::Vector)
An alias for `internal_rate_of_return`.
```

`FinanceCore.present_value`

— Method`present_value(yield_model, cashflows[, timepoints=pairs(cashflows)])`

Discount the `cashflows`

vector at the given `yield_model`

, with the cashflows occurring at the times specified in `timepoints`

. If no `timepoints`

given, assumes that cashflows happen at the indices of the cashflows.

If your timepoints are dates, you can convert them into a floating point representation of the time interval using DayCounts.jl.

**Examples**

```
julia> present_value(0.1, [10,20],[0,1])
28.18181818181818
julia> present_value(Continuous(0.1), [10,20],[0,1])
28.096748360719193
julia> present_value(Continuous(0.1), [10,20],[1,2])
25.422989241919232
julia> present_value(Continuous(0.1), [10,20])
25.422989241919232
```

`FinanceCore.rate`

— Method`rate(r::Rate)`

Returns the untyped scalar interest rate represented by the `Rate`

.

**Examples**

```
julia> r =Continuous(0.03)
Yields.Rate{Float64, Continuous}(0.03, Continuous())
julia> rate(r)
0.03
```

`FinanceCore.timepoint`

— Method`timepoint(x,t)`

If `x`

is an object with a defined time component (e.g. a `Cashflow`

), will return that time component, otherwise will return `t`

. This is useful in handling situations where you want to handle either `Cashflow`

s or separate amount and time vectors.

**Example**

```
julia> FinanceCore.timepoint(Cashflow(1.,3.),"ignored")
3.0
julia> FinanceCore.timepoint(1.,4.)
4.0
```

## Unexported API

`FinanceCore.Timepoint`

— Type`Timepoint(a)`

Summary ≡≡≡≡≡≡≡≡≡

Timepoint is a type alias for Union{T,Dates.Date} that can be used to represent a point in time. It can be either a `Dates.Date`

or a `Real`

number. If defined as a real number, the interpretation is the number of (fractional) periods since time zero.

Currently, the usage of `Dates.Date`

is not well supported across the JuliaActuary ecosystem but this type is in place such that it can be built upon further.

Supertype Hierarchy ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡

`Timepoint{T} = Union{T,Dates.Date} <: Any`

`Base.:*`

— Method```
*(Yields.Rate, T)
*(T, Yields.Rate)
```

The multiplication of a Rate with a scalar will inherit the type of the `Rate`

, or the first argument's type if both are `Rate`

s.

`Base.:+`

— Method```
+(Yields.Rate, T<:Real)
+(T<:Real, Yields.Rate)
+(Yields.Rate,Yields.Rate)
```

The addition of a rate with a number will inherit the type of the `Rate`

, or the first argument's type if both are `Rate`

s.

**Examples**

```
julia> Yields.Periodic(0.01,2) + Yields.Periodic(0.04,2)
Yields.Rate{Float64, Yields.Periodic}(0.05000000000000004, Yields.Periodic(2))
julia> Yields.Periodic(0.04,2) + 0.01
Yields.Rate{Float64, Yields.Periodic}(0.05, Yields.Periodic(2))
```

`Base.:-`

— Method```
-(Yields.Rate, T<:Real)
-(T<:Real, Yields.Rate)
-(Yields.Rate, Yields.Rate)
```

The addition of a rate with a number will inherit the type of the `Rate`

, or the first argument's type if both are `Rate`

s.

**Examples**

```
julia> Yields.Periodic(0.04,2) - Yields.Periodic(0.01,2)
Yields.Rate{Float64, Yields.Periodic}(0.030000000000000214, Yields.Periodic(2))
julia> Yields.Periodic(0.04,2) - 0.01
Yields.Rate{Float64, Yields.Periodic}(0.03, Yields.Periodic(2))
```

`Base.:/`

— Method`/(x::Yields.Rate, y::Real)`

The division of a Rate with a scalar will inherit the type of the `Rate`

, or the first argument's type if both are `Rate`

s.

`Base.:<`

— Method`<(x::Rate,y::Rate)`

Convert the second argument to the periodicity of the first and compare the scalar rate values to determine if the first argument has a lower force of interest than the second.

**Examples**

```
julia> Yields.Periodic(0.03,100) < Yields.Continuous(0.03)
true
```

`Base.:>`

— Method`>(Rate,Rate)`

Convert the second argument to the periodicity of the first and compare the scalar rate values to determine if the first argument has a greater force of interest than the second.

**Examples**

```
julia> Yields.Periodic(0.03,100) > Yields.Continuous(0.03)
false
```

`Base.convert`

— Method`convert(cf::Frequency,r::Rate)`

Returns a `Rate`

with an equivalent discount but represented with a different compounding frequency.

**Examples**

```
julia> r = Rate(Periodic(12),0.01)
Rate(0.01, Periodic(12))
julia> convert(Periodic(1),r)
Rate(0.010045960887181016, Periodic(1))
julia> convert(Continuous(),r)
Rate(0.009995835646701251, Continuous())
```

Please open an issue if you encounter any issues or confusion with the package.