Edit docs; start testing new features

docs/src/ref/ref_API.md

@@ -4,7 +4,8 @@
 @defcomp
 MarginalModel
 Model
-add_comp!  
+add_comp! 
+add_shared_param! 
 connect_param!
 create_marginal_model
 delete_param!

docs/src/tutorials/tutorial_2.md

@@ -10,8 +10,6 @@ Working through the following tutorial will require:
 
 **If you have not yet prepared these, go back to the first tutorial to set up your system.**
 
-Note that we have recently released Mimi v1.0.0, which is a breaking release and thus we cannot promise backwards compatibility with version lower than v1.0.0 although several of these tutorials may run properly with older versions. For assistance updating your own model to v1.0.0, or if you are curious about the primary changes made, see the How-to Guide on porting to Mimi v1.0.0. Mimi v0.10.0 is functionally dentical to Mimi v1.0.0, but includes deprecation warnings instead of errors to assist users in porting to v1.0.0.
-
 #### Step 1. Download FUND
 
 The first step in this process is downloading the FUND model, which is now made easy with the Mimi registry. Assuming you have already done the one-time run of the following command to connect your julia installation with the central Mimi registry of Mimi models, as instructed in the first tutorial,

docs/src/tutorials/tutorial_3.md

@@ -10,8 +10,6 @@ Working through the following tutorial will require:
 
 **If you have not yet prepared these, go back to the first tutorial to set up your system.**
 
-Note that we have recently released Mimi v1.0.0, which is a breaking release and thus we cannot promise backwards compatibility with version lower than v1.0.0 although several of these tutorials may run properly with older versions. For assistance updating your own model to v1.0.0, or if you are curious about the primary changes made, see the How-to Guide on porting to Mimi v1.0.0. Mimi v0.10.0 is functionally dentical to Mimi v1.0.0, but includes deprecation warnings instead of errors to assist users in porting to v1.0.0.
-
 ## Introduction
 
 There are various ways to modify an existing model, and this tutorial aims to introduce the Mimi API relevant to this broad category of tasks.  It is important to note that regardless of the goals and complexities of your modifications, the API aims to allow for modification **without alteration of the original code for the model being modified**.  Instead, you will download and run the existing model, and then use API calls to modify it. This means that in practice, you should not need to alter the source code of the model you are modifying. Thus, it is easy to keep up with any external updates or improvements made to that model.
@@ -22,15 +20,21 @@ Possible modifications range in complexity, from simply altering parameter value
 
 Several types of changes to models revolve around the parameters themselves, and may include updating the values of parameters and changing parameter connections without altering the elements of the components themselves or changing the general component structure of the model.  The most useful functions of the common API in these cases are likely **[`update_param!`](@ref)/[`update_params!`](@ref), [`disconnect_param!`](@ref), and [`connect_param!`](@ref)**.  For detail on these functions see the API reference guide, Reference Guide: The Mimi API.
 
-When the original model calls [`set_param!`](@ref), Mimi creates an shared model parameter by the name provided, and stores the provided scalar or array value. The functions [`update_param!`](@ref) and [`update_params!`](@ref) allow you to change the value associated with this shared model parameter. 
+The parameters in the original model receive their values either from exogenously set model parameters through external parameter connections, or from another component's variable through an internal parameter connection.
+
+The functions [`update_param!`](@ref) and [`update_params!`](@ref) allow you to change the value associated with a model parameter. If the model parameter is shared, obtain the shared model parameter name (often this will be the same as the parameter name by default) and use the following to update it:
+```julia
+update_param!(mymodel, :model_parameter_name, newvalues)
+```
 
+If the model parameter is not shared, and thus the value can only be connected to one component/parameter pair, use the following to update it:
 ```julia
-update_param!(mymodel, :parametername, newvalues)
+update_param!(mymodel, :comp_name, :param_name newvalues)
 ```
 
 Note here that `newvalues` must be the same type (or be able to convert to the type) of the old values stored in that parameter, and the same size as the model dimensions indicate.
 
-If you wish to alter connections within an existing model, [`disconnect_param!`](@ref) and [`connect_param!`](@ref) can be used in conjunction with each other to update the connections within the model, although this is more likely to be done as part of larger changes involving components themslves, as discussed in the next subsection.
+The functions [`disconnect_param!`](@ref) and [`connect_param!`](@ref) can be used to  to alter or add connections within an existing model. These two can be used in conjunction with each other to update the connections within the model, although this is more likely to be done as part of larger changes involving components themselves, as discussed in the next subsection.
 
 ## Parametric Modifications: DICE Example
 
@@ -76,7 +80,7 @@ In the case that you wish to alter an exogenous parameter, you may use the [`upd
 using Mimi
 ```
 
-In DICE the parameter `fco22x` is the forcings of equilibrium CO2 doubling in watts per square meter, and exists in the components `climatedynamics` and `radiativeforcing`.  We can change this value from its default value of `3.200` to `3.000` in both components, using the following code:
+In DICE the parameter `fco22x` is the forcings of equilibrium CO2 doubling in watts per square meter, and is a shared model parameter with the same name that is connected to components `climatedynamics` and `radiativeforcing`.  We can change this value from its default value of `3.200` to `3.000` in both components, using the following code:
 
 ```julia
 update_param!(m, :fco22x, 3.000)
@@ -85,7 +89,7 @@ run(m)
 
 A more complex example may be a situation where you want to update several parameters, including some with a `:time` dimension, in conjunction with altering the time index of the model itself. DICE uses a default time horizon of 2005 to 2595 with 10 year increment timesteps.  If you wish to change this, say, to 1995 to 2505 by 10 year increment timesteps and use parameters that match this time, you could use the following code:
 
-First you upate the `time` dimension of the model as follows:
+First you update the `time` dimension of the model as follows:
 
 ```julia
 const ts = 10
@@ -96,7 +100,7 @@ set_dimension!(m, :time, years)
 
 At this point all parameters with a `:time` dimension have been slightly modified under the hood, but the original values are still tied to their original years.  In this case, for example, the model parameter has been shorted by 9 values (end from 2595 --> 2505) and padded at the front with a value of `missing` (start from 2005 --> 1995). Since some values, especially initializing values, are not time-agnostic, we maintain the relationship between values and time labels.  If you wish to attach new values, you can use `update_param!` as below.  In this case this is probably necessary, since having a `missing` in the first spot of a parameter with a `:time` dimension will likely cause an error when this value is accessed.
 
-Create a dictionary `params` with one entry `(k, v)` per model parameter you want to update by name `k` to value `v`. Each key `k` must be a symbol or convert to a symbol matching the name of a shared model parameter that already exists in the model definition.  Part of this dictionary may look like:
+To batch update **shared** model parameters, create a dictionary `params` with one entry `(k, v)` per model parameter you want to update by name `k` to value `v`. Each key `k` must be a symbol or convert to a symbol matching the name of a shared model parameter that already exists in the model definition.  Part of this dictionary may look like:
 
 ```julia
 params = Dict{Any, Any}()
@@ -107,13 +111,23 @@ params[:S]          = repeat([0.23], nyears)
 ...
 ```
 
+To batch update **unshared** model parameters, follow a similar pattern but use tuples (:comp_name, :param_name) as your dictionary keys, which might look like:
+
+```julia
+params = Dict{Any, Any}()
+params[(:comp1, :a1)]         = 0.00008162
+params[(:comp1, :a2)]         = 0.00204626
+...
+params[(:comp2, :S)]          = repeat([0.23], nyears)
+...
+```
+
 Now you simply update the parameters listen in `params` and re-run the model with
 
 ```julia
 update_params!(m, params)
 run(m)
 ```
-
 ## Component and Structural Modifications: The API
 
 Most model modifications will include not only parametric updates, but also structural changes and component modification, addition, replacement, and deletion along with the required re-wiring of parameters etc. The most useful functions of the common API, in these cases are likely **[`replace!`](@ref), [`add_comp!`](@ref)** along with **`delete!`** and the requisite functions for parameter setting and connecting.  For detail on the public API functions look at the API reference. 

docs/src/tutorials/tutorial_4.md

@@ -11,8 +11,6 @@ Working through the following tutorial will require:
 
 **If you have not yet prepared these, go back to the first tutorial to set up your system.**
 
-Note that we have recently released Mimi v1.0.0, which is a breaking release and thus we cannot promise backwards compatibility with version lower than v1.0.0 although several of these tutorials may run properly with older versions. For assistance updating your own model to v1.0.0, or if you are curious about the primary changes made, see the How-to Guide on porting to Mimi v1.0.0. Mimi v0.10.0 is functionally dentical to Mimi v1.0.0, but includes deprecation warnings instead of errors to assist users in porting to v1.0.0.
-
 ## Constructing A One-Region Model
 
 In this example, we construct a stylized model of the global economy and its changing greenhouse gas emission levels through time. The overall strategy involves creating components for the economy and emissions separately, and then defining a model where the two components are coupled together.

docs/src/tutorials/tutorial_5.md

@@ -11,8 +11,6 @@ Working through the following tutorial will require:
 
 **If you have not yet prepared these, go back to the first tutorial to set up your system.**
 
-Note that we have recently released Mimi v1.0.0, which is a breaking release and thus we cannot promise backwards compatibility with version lower than v1.0.0 although several of these tutorials may run properly with older versions. For assistance updating your own model to v1.0.0, or if you are curious about the primary changes made, see the How-to Guide on porting to Mimi v1.0.0. Mimi v0.10.0 is functionally dentical to Mimi v1.0.0, but includes deprecation warnings instead of errors to assist users in porting to v1.0.0.
-
 MimiDICE2010 is required for the second example in this tutorial. If you are not yet comfortable with downloading and running a registered Mimi model, refer to Tutorial 2 for instructions.
 
 ## The API

examples/01-onecomponent.jl

@@ -6,7 +6,7 @@ using Mimi
 @defcomp component1 begin
 
     # First define the state this component will hold
-    savingsrate = Parameter()
+    savingsrate = Parameter(default = 1.0)
 
     # Second, define the (optional) init function for the component
     function init(p, v, d)

examples/compositecomp-model.jl

@@ -86,13 +86,14 @@ end
 
 # model
 m = Model()
+
 md = m.md
 set_dimension!(m, :time, 2005:2020)
 add_comp!(m, top, nameof(top))
 
-set_param!(m, :fooA1, 1)
-set_param!(m, :fooA2, 2)
-set_param!(m, :foo3, 10)
-set_param!(m, :foo4, 20)
-set_param!(m, :par_1_1, collect(1:length(time_labels(md))))
+update_param!(m, :top, :fooA1, 1)
+update_param!(m, :top, :fooA2, 2)
+update_param!(m, :top, :foo3, 10)
+update_param!(m, :top, :foo4, 20)
+update_param!(m, :top, :par_1_1, collect(1:length(Mimi.time_labels(md))))
 run(m)

examples/tutorial/01-one-region-model/one-region-model.jl

@@ -43,18 +43,17 @@ function construct_model()
 	add_comp!(m, grosseconomy)  
 	add_comp!(m, emissions)
 
-	# Set parameters for the grosseconomy component
-	set_param!(m, :grosseconomy, :l, [(1. + 0.015)^t *6404 for t in 1:20])
-	set_param!(m, :grosseconomy, :tfp, [(1 + 0.065)^t * 3.57 for t in 1:20])
-	set_param!(m, :grosseconomy, :s, ones(20).* 0.22)
-	set_param!(m, :grosseconomy, :depk, 0.1)
-	set_param!(m, :grosseconomy, :k0, 130.)
-	set_param!(m, :grosseconomy, :share, 0.3)
-
-	# Set parameters for the emissions component
-	set_param!(m, :emissions, :sigma, [(1. - 0.05)^t *0.58 for t in 1:20])
+	# Update parameters for the grosseconomy component
+	update_param!(m, :grosseconomy, :l, [(1. + 0.015)^t *6404 for t in 1:20])
+	update_param!(m, :grosseconomy, :tfp, [(1 + 0.065)^t * 3.57 for t in 1:20])
+	update_param!(m, :grosseconomy, :s, ones(20).* 0.22)
+	update_param!(m, :grosseconomy, :depk, 0.1)
+	update_param!(m, :grosseconomy, :k0, 130.)
+	update_param!(m, :grosseconomy, :share, 0.3)
+
+	# Update and connect parameters for the emissions component
+	update_param!(m, :emissions, :sigma, [(1. - 0.05)^t *0.58 for t in 1:20])
 	connect_param!(m, :emissions, :YGROSS, :grosseconomy, :YGROSS)  
-    # Note that connect_param! was used here.
 
 	return m
 

examples/tutorial/02-multi-region-model/multi-region-model.jl

@@ -19,15 +19,16 @@ function construct_MyModel()
 	add_comp!(m, grosseconomy)
 	add_comp!(m, emissions)
 
-	set_param!(m, :grosseconomy, :l, l)
-	set_param!(m, :grosseconomy, :tfp, tfp)
-	set_param!(m, :grosseconomy, :s, s)
-	set_param!(m, :grosseconomy, :depk, depk)
-	set_param!(m, :grosseconomy, :k0, k0)
-	set_param!(m, :grosseconomy, :share, 0.3)
-
-	# set parameters for emissions component
-	set_param!(m, :emissions, :sigma, sigma)
+	# update parameters for grosseconomy component
+	update_param!(m, :grosseconomy, :l, l)
+	update_param!(m, :grosseconomy, :tfp, tfp)
+	update_param!(m, :grosseconomy, :s, s)
+	update_param!(m, :grosseconomy, :depk, depk)
+	update_param!(m, :grosseconomy, :k0, k0)
+	update_param!(m, :grosseconomy, :share, 0.3)
+
+	# update and connect parameters for emissions component
+	update_param!(m, :emissions, :sigma, sigma)
 	connect_param!(m, :emissions, :YGROSS, :grosseconomy, :YGROSS)
 
     return m

src/Mimi.jl

@@ -16,6 +16,7 @@ export
     MarginalModel,
     Model,
     add_comp!,
+    add_shared_param!,
     # components,
     connect_param!,
     create_marginal_model,