AbstractGBM <: ContinuousUnivariateDistribution

Abstract type for simulating investment growth using Geometric Brownian Motion.

AbstractLogger

An abstract type for recording the state of the model during simulation.

AbstractModel

An abstract model type for simulating retirement investments.

AbstractState

An abstract type for tracking the state of the model during simulation.

AbstractTransaction{T, D}

An abstract type for scheduling transactions.

GBM{T <: Real} <: AbstractGBM

A distribution object for Geometric Brownian Motion (GBM), which is used to model growth of stocks.

Fields

• μ::T: growth rate
• σ::T: volitility in growth rate
• μᵣ::T: growth rate during recession
• σᵣ::T: volitility in growth rate during recession
• x0::T: initial value of stock
• x::T: current value

VarGBM{T <: Real} <: AbstractGBM

A distribution object for variable Geometric Brownian Motion (vGBM), which is used to model growth of stocks. Unlike GBM, vGBM selects growth rate (μ) and volitility (σ) parameters from a normal distribution on each simulation run to capture uncertainy in these parameters.

Fields

• μ::T: growth rate sampled from normal distribution
• σ::T: volitility in growth rate during, sampled from truncated normal distribution
• μᵣ::T: growth rate during a recession sampled from normal distribution
• σᵣ::T: volitility in growth rate during a recession, sampled from truncated normal distribution
• αμ::T: mean of growth rate distribution
• ασ::T: mean of volitility of growth rate distribution
• ημ::T: standard deviation of growth rate distribution
• ησ::T: standard deviation of volitility of growth rate distribution
• αμ::T: mean of growth rate distribution during a recession
• ασ::T: mean of volitility of growth rate distribution during a recession
• ημ::T: standard deviation of growth rate distribution during a recession
• ησ::T: standard deviation of volitility of growth rate distribution during a recession
• x0::T: initial value of stock
• x::T: current value

Constructor

VarGBM(; αμ, ασ, ημ, ησ, x0=1.0, x=x0)

MvGBM{T <: Real} <: AbstractGBM

A distribution object for Multivariate Geometric Brownian Motion (MvGBM), which is used to model growth of multiple stocks and bonds.

Fields

• μ::Vector{T}: growth rates
• σ::Vector{T}: volitility in growth rates
• x0::Vector{T}: initial value of stocks
• x::Vector{T}: value of stocks
• ratios::Vector{T}: allocation proportion of stocks/bonds
• ρ::Array{T, 2}: correlation matrix between stocks/bonds
• Σ::Array{T, 2}: covariance matrix between stocks/bonds

Constructor

MvGBM(; μ, σ, ρ, ratios)

Model{S, R, T <: Real} <: AbstractModel

The default retirement simulation Model.

Fields

• Δt::T: the time step of the simulation in years
• duration::T: the duration of the simulation in years
• start_age::T: age at the beginning of the simulation
• start_amount::T: initial investment amount
• log_times::R: a collection of ordered times to log data
• state::S: the current state of the system
• withdraw!: a function called on each time step to withdraw from investments
• invest!: a function called on each time step to invest money into investments
• update_income!: a function called on each time step to update income sources
• update_inflation!: a function called on each time step to compute inflation
• update_market!: a function called on each time step to compute interest on investments
• update_investments!: a function called on each time step to compute net worth
• log!: a function called on each time step to log data

Constructor

Model(;
    Δt,
    duration,
    start_age,
    start_amount,
    log_times,
    state = State(),
    withdraw! = withdraw!,
    invest! = invest!,
    update_income! = update_income!,
    update_inflation! = dynamic_inflation,
    update_market! = dynamic_market,
    update_investments! = update_investments!,
    log! = default_log!,
    config...
)

State{T<:Real} <: AbstractState

Represents the state of the model, which is updated on each iteration.

Fields

• interest_rate::T: interest rate of investment during the current time period
• inflation_rate::T: the inflation rate during the current time period
• income_amount::T: income during the current time period from various sources, e.g., social security, pension, etc.
• invest_amount::T: the amount invested during the current time period
• withdraw_amount::T: the amount deducted from investments during the current time period
• net_worth::T: total value of the investment during the current time period
• log_idx::Int: the index of the current time step to be logged

Logger{T <: Real} <: AbstractLogger

An object for storing variables of the simulation.

Fields

• net_worth::Array{T, 2}: total value of investments
• interest::Array{T, 2}: growth rate of investment
• inflation::Array{T, 2}: inflation rate
• total_income::Array{T, 2}: income from investment withdraws, social security etc.

In each array above, rows are time steps and columns are repetitions of the simulation.

Transaction{T, D} <: AbstractTransaction{T, D}

Specifies the time range and amount of a transaction.

Fields

• start_age = 0.0: the age at which a series of transactions begin
• end_age = Inf: the age at which a series of transactions end
• amount = 0: the amount of each transaction

Constructor

Transaction(; start_age = 0.0, end_age = Inf, amount = 0)

get_times(model::AbstractModel)

Returns the time steps used in the simulation.

Arguments

• model::AbstractModel: an abstract Model object

grid_search(
    model_type::Type{<:AbstractModel},
    Logger::Type{<:AbstractLogger},
    n_reps,
    all_args;
    threaded::Bool = false,
    show_progress::Bool = false,
    yoked_values = ()
)

Performs a grid search over vectorized inputs specified in the configuration setup. As an example, consider the following configuration setup:

config = (
    Δt = 1 / 12,
    start_age = 30.,
    duration = 55.0,
    start_amount = 10_000.0,
    # withdraw parameters 
    kw_withdraw = (
        distribution = [
            Normal(3000, 1000), 
            Normal(4000, 1000),
        ],
        start_age = 65,
    ),
    # invest parameters
    kw_invest = (
        distribution = [
            Normal(1000, 100),
            Normal(1500, 100),
        ]
        end_age = 65,
    ),
    # interest parameters
    kw_market = (
        gbm = GBM(; μ = .07, σ = .05),
    ),
    # inflation parameters
    kw_inflation = (
        gbm = GBM(; μ = .035, σ = .005),
    )
)

In the example above, four simulations will be performed: one for each combination of withdraw distribution and investment distribution.

Arguments

• model_type::Type{<:AbstractModel}: an abstract model type for performing Monte Carlo simulations of investment scenarios
• Logger::Type{<:AbstractLogger}: a type for collecting variables of the simulation. The constructor signature is Logger(; n_reps, n_steps)
• n_reps: the number of times the investiment simulation is repeated for each input combination.
• all_args: a NamedTuple of configuration settings

Keywords

• threaded::Bool = false: runs simulations on separate threads if true
• show_progress::Bool = false: shows progress bar if true
• yoked_values = (): fix specified inputs to have the same values, such as: [Pair((:kw_withdraw, :start_age), (:kw_invest, :end_age))]

Output

Returns a vector of tuples where each tuple corresponds to the result of a single simulation condition. Each tuple consists of input values and output results. The function to_dataframe can be used to transform output into a long-form DataFrame.

Notes

This function was inspired by parmscan in Agents.jl.

is_event_time(model::AbstractModel, t, rate)

Indicate whether it is time for a periodic event to occur.

Arguments

• model::AbstractModel: an abstract Model object
• t: current time (or age) in years
• rate: the interval between repeating events measured in years

rand(dist::AbstractGBM, n_steps, n_reps; Δt)

Simulate a random trajectory of a Geometric Brownian motion process.

Arguments

• dist::AbstractGBM: a distribution object for Geometric Brownian Motion
• n_steps: the number of discrete time steps in the simulation
• n_reps: the number of times the simulation is repeated

Keywords

• Δt: the time step for Geometric Brownian Motion

simulate!(model::AbstractModel, logger::AbstractLogger, n_reps)

Simulate the a retirement scenario a specified number of times.

Arguments

• model::AbstractModel: an abstract Model object
• logger::AbstractLogger: an object for storing variables of the simulation
• n_reps: the number of times to repeat the Monte Carlo simulation

transact(
    model::AbstractModel,
    income::Transaction{T, D};
    t
) where {T, D <: Distribution}

Sample a amount from a specified distribution and execute a transaction.

Arguments

• ::AbstractModel: unused model object
• investment::Transaction{T, D}: a transaction object specifing an investment rule

Keywords

• t: the current time

transact(
    model::AbstractModel,
    income::Transaction{T, D};
    t
) where {T, D <: NominalAmount}

Execute a transaction using the nominal value of the transaction amount.

Arguments

• ::AbstractModel: unused model object
• investment::Transaction{T, D}: a transaction object specifing an investment rule

Keywords

• t: the current time

transact(
    ::AbstractModel,
    investment::Transaction{T, D};
    t
) where {T, D <: AdaptiveInvestment}

Execute an adaptive investment transaction in which the real invested amount increased until reaching a peak earning potential.

Arguments

• ::AbstractModel: unused model object
• investment::Transaction{T, D}: a transaction object specifing an investment rule

Keywords

• t: the current time

update!(model::AbstractModel, logger::AbstractLogger, step, rep, t)

Performs an update on each time step by calling the following functions defined in model:

• update_inflation!: compute inflation
• update_market!: compute interest
• invest!: invest money
• withdraw!: withdraw money
• update_income!: update sources of income, such as social security, pension etc.
• update_investments!: compute net worth for the time step
• log!: log desired variables

Each function except log! has the signature my_func(model, t; kwargs...). The function log! has the signature log!(model, logger, step, rep; kwargs...).

Arguments

• model::AbstractModel: an abstract Model object
• rep::Int: repetition count of simulation
• time_step::Int: time step count of simulation
• t: time in years

update_income!(
    model::AbstractModel,
    t;
    income_sources = Transaction(0.0, -1.0, 0.0)
)

Recieve income from specified sources on each time step, as indicated by income_sources.

Arguments

• model::AbstractModel: an abstract Model object
• t: current time of simulation in years

Keywords

• income_sources = Transaction(0.0, -1.0, 0.0): a transaction or vector of transactions indicating the amount and time period of income recieved per time step

fixed_inflation(
    model::AbstractModel, 
    t;
    inflation_rate = .03
)

Returns a fixed inflation rate of a specified value.

Arguments

• model::AbstractModel: an abstract Model object
• t: current time of simulation in years

Keywords

• inflation_rate = .03: a constant rate of inflation per year

variable_inflation(
    model::AbstractModel,
    t;
    distribution = Normal(.03, .01)
)

Returns an interest rate sampled from a specified distribution.

Arguments

• model::AbstractModel: an abstract Model object
• t: current time of simulation in years

Keywords

• distribution = Normal(.03, .01): the distribution of inflation per year

dynamic_inflation(
    model::AbstractModel, 
    t; 
    gbm = GBM(; μ=.03, σ=.01, x0=1),
    kwargs...
)

Models inflation in the stock market as a geometric brownian motion process.

Arguments

• model::AbstractModel: an abstract Model object
• t: current time of simulation in years

Keyword

• gbm = GBM(; μ=.03, σ=.01, x0=1): a geometric brownian motion object with parameters μ reflecting mean growth rate, and σ reflecting volitility in growth rate. The parameter x0 sets an arbitrary scale. The function also supports VarGBM.
• kwargs...: optional keyword arguments passed to increment!

fixed_market(model::AbstractModel, t; interest_rate = .07)

Returns a fixed interesting rate using a specified value.

Arguments

• model::AbstractModel: an abstract Model object
• t: current time of simulation in years

Keywords

• interest_rate = .07: a constant rate of investment growth per year

variable_market(
    model::AbstractModel,
    t;
    distribution = Normal(.07, .05)
)

Returns interest rate sampled from a specified distribution.

Arguments

• model::AbstractModel: an abstract Model object
• t: current time of simulation in years

Keywords

• distribution = Normal(.07, .05): the distribution of interest per year

dynamic_market(
    model::AbstractModel,
    t;
    rebalance_rate = Inf,
    gbm = GBM(; μ = 0.07, σ = 0.05, x0 = 1),
    kwargs...
)

Models the stock market as a geometric brownian motion process.

Arguments

• model::AbstractModel: an abstract Model object
• t: current time of simulation in years

Keyword

• gbm = GBM(; μ=.07, σ=.05, x0=1): a geometric Brownian motion object with parameters μ reflecting mean growth rate, and σ reflecting volitility in growth rate. The parameter x0 sets an arbitrary scale. Other variations of geometric Brownian motion can be used, including VarGBM and MvGBM
• rebalance_rate = Inf: the time elapsed in years between rebalacing the portfolio. Not applicable to GBM
• kwargs...: optional keyword arguments passed to increment!

invest!(
    model::AbstractModel,
    t;
    investments = Transaction(0.0, -1.0, 0.0),
    real_growth = 0.0,
    peak_age = 45
)

Contribute a specified amount into investments on each time step.

Arguments

• model::AbstractModel: an abstract Model object
• t: current time of simulation in years

Keywords

• investments = Transaction(0.0, -1.0, 0.0): a transaction or vector of transactions indicating the time frame and amount to invest

default_log!(model::AbstractModel, logger, rep, t; _...)

Logs the following information on each time step of each simulation repetition:

• net worth
• interest rate
• inflation rate
• total_income

Arguments

• model::AbstractModel: an abstract Model object
• logger: a logger object
• rep: indexes the repetition of the simulation
• t: current time in years

Keywords

• _...: optional keyword arguments which are not used

update_investments!(model::AbstractModel, t)

Computes net worth for the current time step as follows:

1. withdraw money
2. contribute money
3. multiply by real growth rate.

Arguments

• model::AbstractModel: an abstract Model object
• t: current time of simulation in years

withdraw!(
    model::AbstractModel,
    t;
    withdraws = Transaction(0.0, -1.0, 0.0)
)

Schedules withdraws from investments as specified in withdraws.

Arguments

• model::AbstractModel: an abstract Model object
• t: current time of simulation in years

Keywords

• withdraws = Transaction(0.0, -1.0, 0.0): a transaction or vector of transactions indicating the amount and time period in which money is withdrawn from investments per time step