Rename model stepping functions (#42)

* Rename model stepping functions

* Update Project.toml

Project.toml

@@ -1,10 +1,11 @@
 name = "BeforeIT"
 uuid = "ca9fcad7-41d0-4f76-b1e5-366c28bce52e"
 authors = ["Aldo Glielmo <aldo.glielmo@bancaditalia.it>", "Mitja Devetak <m888itja@gmail.com>", "Adriano Meligrana <adrianomeligrana@proton.me>"]
-version = "0.2.0"
+version = "0.3.0"
 
 [deps]
 ChunkSplitters = "ae650224-84b6-46f8-82ea-d812ca08434e"
+CommonSolve = "38540f10-b2f7-11e9-35d8-d573e4eb0ff2"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 DynamicSampling = "2083aeaf-6258-5d07-89fc-32cf5060c837"
@@ -22,6 +23,7 @@ StatsPlots = "f3b207a7-027a-5e70-b257-86293d7955fd"
 
 [compat]
 ChunkSplitters = "3"
+CommonSolve = "0.2"
 Dates = "1"
 Distributions = "0.25"
 DynamicSampling = "0.4"

README.md

@@ -69,7 +69,7 @@ initial_conditions = BeforeIT.AUSTRIA2010Q1.initial_conditions
 
 T = 20
 model = BeforeIT.init_model(parameters, initial_conditions, T)
-data = BeforeIT.run_one_sim!(model)
+data = BeforeIT.run!(model)
 ```
 
 This will simulate the model with the original Austrian parametrisation for 20 quarters and save the results in the `data` object.

docs/src/index.md

@@ -36,7 +36,7 @@ initial_conditions = BeforeIT.AUSTRIA2010Q1.initial_conditions
 
 T = 20
 model = BeforeIT.initialise_model(parameters, initial_conditions, T)
-data = BeforeIT.run_one_sim!(model)
+data = BeforeIT.run!(model)
 ```
 
 To plot the results of the simulation, you can use the `Plots` package

examples/basic_example.jl

@@ -31,12 +31,12 @@ data = Bit.init_data(model);
 # We can run now the model for a number of epochs and progressively update the data tracker.
 
 for t in 1:T
-    Bit.run_one_epoch!(model; multi_threading = true)
+    Bit.step!(model; multi_threading = true)
     Bit.update_data!(data, model)
 end
 
 # Note that we can equivalently run the model for a number of epochs in the single command 
-# `data = BeforeIT.run_one_sim!(model)`, but writing the loop explicitely is more instructive.
+# `data = BeforeIT.run!(model)`, but writing the loop explicitely is more instructive.
 
 # We can then plot any time series stored in the data tracker, for example
 
@@ -50,7 +50,7 @@ plot(ps..., layout = (3, 3))
 # To run multiple monte-carlo repetitions in parallel we can use
 
 model = Bit.init_model(parameters, initial_conditions, T)
-data_vector = Bit.run_n_sims(model, 4)
+data_vector = Bit.ensemblerun(model, 4)
 
 # Note that this will use the number of threads specified when activating the Julia environment.
 # To discover the number of threads available, you can use the command 

examples/benchmark_w_matlab.jl

@@ -13,7 +13,7 @@ function run(parameters, initial_conditions, T; multi_threading = false)
     data = BeforeIT.init_data(model);
 
     for _ in 1:T
-        BeforeIT.run_one_epoch!(model; multi_threading = multi_threading)
+        BeforeIT.step!(model; multi_threading = multi_threading)
         BeforeIT.update_data!(data, model)
     end
     return model, data

examples/change_expectations.jl

@@ -16,7 +16,7 @@ init = Bit.AUSTRIA2010Q1.initial_conditions
 Random.seed!(1234)
 T = 40
 model = Bit.init_model(par, init, T)
-data = Bit.run_one_sim!(model)
+data = Bit.run!(model)
 
 # Now we can experiment with changing expectations of the agents in the model.
 # We will change the function `estimate_next_value` to make the agents expect 
@@ -31,7 +31,7 @@ end
 
 Random.seed!(1234)
 model = Bit.init_model(par, init, T)
-data_back = Bit.run_one_sim!(model)
+data_back = Bit.run!(model)
 
 # Plot the results, comparing the two cases as different lines
 

examples/get_simulations.jl

@@ -17,7 +17,7 @@ for year in 2010:2019
         T = 12
         model = BeforeIT.init_model(parameters, initial_conditions, T)
         n_sims = 4
-        data_vector = BeforeIT.run_n_sims(model, n_sims)
+        data_vector = BeforeIT.ensemblerun(model, n_sims)
         save("data/italy/simulations/" * string(year) * "Q" * string(quarter) * ".jld2", "data_vector", data_vector)
     end
 end

examples/multithreading_speedup.jl

@@ -26,13 +26,13 @@ Threads.nthreads()
 
 # Then we need to first compile the code not to count compilation time,
 # we can do that just by executing the function one time
-Bit.run_one_sim!(model; multi_threading = false);
+Bit.run!(model; multi_threading = false);
 
 # Let's now compare the performance of single threading and multi threading
 model = Bit.init_model(parameters, initial_conditions, T);
-@time data = Bit.run_one_sim!(model; multi_threading = false);
+@time data = Bit.run!(model; multi_threading = false);
 
 model = Bit.init_model(parameters, initial_conditions, T);
-@time data = Bit.run_one_sim!(model; multi_threading = true);
+@time data = Bit.run!(model; multi_threading = true);
 
 # Is the speedup in line to what we would expect? Yes!

examples/scenario_analysis_via_overload.jl

@@ -18,7 +18,7 @@ data = Bit.init_data(model);
 
 # Simulate the model for T quarters
 
-data_vec_baseline = Bit.run_n_sims(model, 4)
+data_vec_baseline = Bit.ensemblerun(model, 4)
 
 # Now, apply a shock to the model and simulate it again
 # Here, we do this by overloading the central_bank_rate function with the wanted behaviour
@@ -36,7 +36,7 @@ function central_bank_rate(cb::Bit.CentralBank, model::Bit.Model)
     end
 end
 
-data_vec_shocked = Bit.run_n_sims(model, 4)
+data_vec_shocked = Bit.ensemblerun(model, 4)
 
 # Finally, we can plot baseline and shocked simulations
 

examples/scenario_analysis_via_shock.jl

@@ -15,7 +15,7 @@ T = 20
 model = Bit.init_model(parameters, initial_conditions, T);
 
 # Simulate the model for T quarters
-data_vec_baseline = Bit.run_n_sims(model, 4)
+data_vec_baseline = Bit.ensemblerun(model, 4)
 
 # Now, apply a shock to the model and simulate it again.
 # A shock is simply a function that takes the model and changes some of
@@ -42,7 +42,7 @@ end
 # and run a shocked simulation
 
 custom_shock = CustomShock(0.0, 10)
-data_vec_shocked = Bit.run_n_sims(model, 4; shock = custom_shock)
+data_vec_shocked = Bit.ensemblerun(model, 4; shock = custom_shock)
 
 # Finally, we can plot baseline and shocked simulations
 

main.jl

@@ -10,7 +10,7 @@ data = BeforeIT.init_data(model)
 
 for t in 1:T
     println("Epoch: ", t)
-    BeforeIT.run_one_epoch!(model; multi_threading = true)
+    BeforeIT.step!(model; multi_threading = true)
     BeforeIT.update_data!(data, model)
 end
 

src/model_init/abstract.jl

@@ -17,6 +17,7 @@ abstract type AbstractBank end
 abstract type AbstractCentralBank end
 abstract type AbstractGovernment end
 abstract type AbstractRestOfTheWorld end
+abstract type AbstractModel end
 
 macro worker(T = Vector{Float64}, I = Vector{Int})
     return esc(quote

src/model_init/agents.jl

@@ -222,7 +222,7 @@ This is a Model type. It is used to store all the agents of the economy.
 - `rotw`: RestOfTheWorld
 - `agg`: Aggregates
 """
-mutable struct Model
+mutable struct Model <: AbstractModel
     w_act::AbstractWorkers
     w_inact::AbstractWorkers
     firms::AbstractFirms

src/one_epoch.jl

@@ -1,7 +1,10 @@
 
+import CommonSolve
+using CommonSolve: step!
+export step!
 
 """
-    run_one_epoch!(model; multi_threading = false)
+    step!(model; multi_threading = false)
 
 This function simulates a single epoch the economic model, updating various components of the model based 
 the interactions between different economic agents. It accepts a `model` object, which encapsulates the state for the
@@ -17,7 +20,7 @@ Key operations performed include:
 
 The function updates the model in-place and does not return any value.
 """
-function run_one_epoch!(model; multi_threading = false, shock = NoShock())
+function CommonSolve.step!(model::AbstractModel; multi_threading = false, shock = NoShock())
 
     gov = model.gov # government
     cb = model.cb # central bank

src/one_simulation.jl

@@ -1,5 +1,5 @@
 """
-    run_one_sim!(model; shock = NoShock())
+    run!(model; shock = NoShock())
 
 Run a single simulation based on the provided `model`. 
 The simulation runs for a number of epochs specified by `model.prop.T`.
@@ -12,21 +12,21 @@ The simulation runs for a number of epochs specified by `model.prop.T`.
 
 # Details
 The function initializes the data using `BeforeIT.init_data(model)`, then iteratively updates the model and data
-for each epoch using `BeforeIT.run_one_epoch!(model)` and `BeforeIT.update_data!(data, model)` respectively.
+for each epoch using `BeforeIT.step!(model)` and `BeforeIT.update_data!(data, model)` respectively.
 
 # Example
 ```julia
 model = BeforeIT.init_model(parameters, initial_conditions, T)
-data = run_one_sim!(model)
+data = run!(model)
 """
-function run_one_sim!(model; multi_threading = false, shock = NoShock())
+function run!(model::AbstractModel; multi_threading = false, shock = NoShock())
 
     data = BeforeIT.init_data(model)
 
     T = model.prop.T
 
     for _ in 1:T
-        BeforeIT.run_one_epoch!(model; multi_threading = multi_threading, shock = shock)
+        BeforeIT.step!(model; multi_threading = multi_threading, shock = shock)
         BeforeIT.update_data!(data, model)
     end
 
@@ -36,7 +36,7 @@ end
 
 
 """
-    run_n_sims(model, n_sims; shock = NoShock(), multi_threading = true)
+    ensemblerun(model, n_sims; shock = NoShock(), multi_threading = true)
 
 A function that runs `n_sims` simulations in parallel with multiple threading and returns a vector of 
 data objects of dimension `n_sims`.
@@ -48,20 +48,20 @@ data objects of dimension `n_sims`.
 # Returns
 - `data_vector`: A vector containing the data objects collected during each simulation.
 """
-function run_n_sims(model, n_sims; multi_threading = true, shock = NoShock())
+function ensemblerun(model::AbstractModel, n_sims; multi_threading = true, shock = NoShock())
 
     data_vector = Vector{BeforeIT.Data}(undef, n_sims)
 
     if multi_threading
         Threads.@threads for i in 1:n_sims
             model_i = deepcopy(model)
-            data = run_one_sim!(model_i; shock = shock)
+            data = run!(model_i; shock = shock)
             data_vector[i] = data
         end
     else
         for i in 1:n_sims
             model_i = deepcopy(model)
-            data = run_one_sim!(model_i; shock = shock)
+            data = run!(model_i; shock = shock)
             data_vector[i] = data
         end
     end

src/precompile.jl

@@ -8,7 +8,7 @@ using PrecompileTools
     @compile_workload let
         model = BeforeIT.init_model(parameters, initial_conditions, T)
 	data = BeforeIT.init_data(model);
-	BeforeIT.run_one_epoch!(model)
+	BeforeIT.step!(model)
 	BeforeIT.update_data!(data, model)
     end
 end

src/utils/data.jl

@@ -146,7 +146,7 @@ Update the data `d` with the model `m`.
 
 ```julia
 data = BeforeIT.init_data(model)
-run_one_epoch!(model)
+step!(model)
 BeforeIT.update_data!(data, model)
 ```
 """

test/accounting_identities.jl

@@ -12,7 +12,7 @@ using Test
     data = BeforeIT.init_data(model)
 
     for t in 1:T
-        BeforeIT.run_one_epoch!(model; multi_threading = false)
+        BeforeIT.step!(model; multi_threading = false)
         BeforeIT.update_data!(data, model)
     end
 

test/deterministic/deterministic_ouput_t1_t5.jl

@@ -7,7 +7,7 @@
     model = BeforeIT.init_model(parameters, initial_conditions, T)
     data = BeforeIT.init_data(model)
 
-    BeforeIT.run_one_epoch!(model; multi_threading = false)
+    BeforeIT.step!(model; multi_threading = false)
     BeforeIT.update_data!(data, model)
 
     # import results from matlab run
@@ -33,7 +33,7 @@
     model = BeforeIT.init_model(parameters, initial_conditions, T)
     data = BeforeIT.init_data(model)
     for t in 1:T
-        BeforeIT.run_one_epoch!(model; multi_threading = false)
+        BeforeIT.step!(model; multi_threading = false)
         BeforeIT.update_data!(data, model)
     end
 

test/deterministic/one_run_deterministic.jl

@@ -8,7 +8,7 @@
         model = BeforeIT.init_model(parameters, initial_conditions, T;)
         data = BeforeIT.init_data(model)
         for t in 1:(T - 1)
-            BeforeIT.run_one_epoch!(model; multi_threading = m)
+            BeforeIT.step!(model; multi_threading = m)
             BeforeIT.update_data!(data, model)
         end
         return model, data   

test/monte_carlo_evaluations.jl

@@ -10,7 +10,7 @@ model = BeforeIT.init_model(parameters, initial_conditions, T)
 data = BeforeIT.init_data(model)
 
 n_sims = 3
-data_vector = BeforeIT.run_n_sims(model, n_sims)
+data_vector = BeforeIT.ensemblerun(model, n_sims)
 
 @test length(data_vector) == n_sims
 @test typeof(data_vector) == Vector{BeforeIT.Data}

test/steady_state.jl

@@ -10,7 +10,7 @@ data = BeforeIT.init_data(model)
 
 for t in 1:T
     println(t)
-    BeforeIT.run_one_epoch!(model; multi_threading = false)
+    BeforeIT.step!(model; multi_threading = false)
     BeforeIT.update_data!(data, model)
 end