Attribute VB_Name = "RiskAMP_VBAModule"

'==============================================================
'
' VBA function library for calling RiskAMP Add-in functions.
' The RiskAMP Add-in is a native, compiled DLL.  Functions can
' be called from VBA using the ExecuteExcel4Macro function,
' but this is unwieldy in application code.  The functions
' in this library can simplify writing VBA applications using
' the RiskAMP library.
'
' Copyright 2010-2022 Structured Data, LLC
'
'==============================================================

'--------------------------------------------------------------
'
' Function: RiskAMP_RunSimulation
'
' Run a Monte Carlo simulation with the
' given number of trials.
'
Function RiskAMP_RunSimulation( Optional ByVal NumberOfTrials As Integer = 250 )

    Application.ExecuteExcel4Macro ("RunSimulation(" & NumberOfTrials & ")")

End Function

'--------------------------------------------------------------
'
' Function: RiskAMP_NormalValue
'
' return a sample value from the normal (gaussian) distribution.
' if no parameters are passed, the default distribution has a
' mean of 0 and a standard deviation of 1.
'
Function RiskAMP_NormalValue(Optional ByVal Mean As Double = 0, Optional ByVal StandardDeviation As Double = 1) As Double

    RiskAMP_NormalValue = Application.ExecuteExcel4Macro("NormalValue(" & Mean & ", " & StandardDeviation & ")")

End Function

'--------------------------------------------------------------
'
' Function: RiskAMP_BetaPERTValue
'
' return a sample value from the betaPERT distribution.  the Lambda
' parameter controls the shape of the distribution; the default is 4.
'
Function RiskAMP_BetaPERTValue(ByVal Minimum As Double, ByVal MostLikely As Double, ByVal Maximum As Double, Optional ByVal Lambda As Double = 4) As Double

    RiskAMP_BetaPERTValue = Application.ExecuteExcel4Macro("PERTValue(" & Minimum & ", " & MostLikely & ", " & Maximum & ", " & Lambda & ")")

End Function

'--------------------------------------------------------------
'
' Function: RiskAMP_ReseedRandomNumberGenerator
'
' re-seed the PRNG (pseudo-random number generator).  pass a seed value
' or 0 to set a time-dependent seed (based on current system time).
'
Function RiskAMP_ReseedRandomNumberGenerator(Optional ByVal Seed As Integer = 0)

    Application.ExecuteExcel4Macro ("RiskAMP_ResetNumberGenerator(" & Seed & ")")

End Function

'--------------------------------------------------------------
'
' Function: RiskAMP_TriangularValue
'
' return a sample value from the triangular distribution.  if no
' parameters are passed to the function, returns a sample from a
' symmetrical distribution with minimum 0, maximum 1 and mode of 0.5.
'
Function RiskAMP_TriangularValue(Optional ByVal Minimum As Double = 0, Optional ByVal MostLikely As Double = 0.5, Optional ByVal Maximum As Double = 1) As Double

    RiskAMP_TriangularValue = Application.ExecuteExcel4Macro("TriangularValue(" & Minimum & ", " & MostLikely & ", " & Maximum & ")")

End Function

'--------------------------------------------------------------
'
' Function: RiskAMP_BeginSteppedSimulation
'
' Start a simulation which is controlled from VBA.  The aim of
' this type of simulation is to allow VBA-specific functions
' to run at each iteration of the simulation, capturing results
' for later analysis.
'
Function RiskAMP_BeginSteppedSimulation(Optional ByVal NumberOfTrials As Integer = 250)

    Application.ExecuteExcel4Macro ("RiskAMP_BeginSteppedSimulation(" & NumberOfTrials & " )")

End Function

'--------------------------------------------------------------
'
' Function: RiskAMP_IterateSimulationStep
'
' In a VBA-controlled simulation, advance one step.  This will
' capture spreadsheet values in any results cells, and update
' random values in the spreadsheet.
'
Function RiskAMP_IterateSimulationStep()

    Application.ExecuteExcel4Macro ("RiskAMP_IterateSimulationStep()")

End Function

'--------------------------------------------------------------
'
' Function: RiskAMP_FinishSteppedSimulation
'
' Complete a VBA-controlled simulation.
'
Function RiskAMP_FinishSteppedSimulation()

    Application.ExecuteExcel4Macro ("RiskAMP_FinishSteppedSimulation()")

End Function