Merge pull request #733 from mimiframework/readme

Docs updates

Author: lrennels

README.md

@@ -7,6 +7,14 @@
 
 Mimi is a [Julia](http://julialang.org) package that provides a component model for [integrated assessment models](https://en.wikipedia.org/wiki/Integrated_assessment_modelling), as described in detail on the [Mimi Framework Homepage](https://www.mimiframework.org). The [Documentation](https://www.mimiframework.org/Mimi.jl/stable/) includes information on the installation and use of this package, step-by-step tutorials, how-to guides, and techincal reference. The development team closely monitors the [Mimi Framework forum](https://forum.mimiframework.org) and we suggest this as a starting place for any questions users may have.
 
+## NEWS
+
+On 7/15/2020 we officially tagged and released Mimi v1.0.0, which has some new features, documentation, and quite a bit of internals work as well.  Since this is a major version change, there are some breaking changes that may require you to update your code.  We have done the updates for the existing models in the Mimi registry (FUND, DICE, etc.), and will release new major versions of those today as well, so if you are using the latest version of Mimi and the latest version of the packages, all should run smoothly.
+
+**Please view the how to guide here: https://www.mimiframework.org/Mimi.jl/stable/howto/howto_6/ for a run-down of how you should update your own code.**
+
+In addition please do not hesitate to ask any questions on the forum, we are working hard to keep this transition smooth.
+
 ## Contributions and Questions
 
 You can interact with the Mimi development team via issues and pull requests here on github, and in the [Mimi Framework forum](https://forum.mimiframework.org). Contributions to Mimi are also most welcome, and

docs/make.jl

@@ -31,9 +31,9 @@ makedocs(
 		"Reference Guides" => Any[
 			"Reference Guides Intro" => "ref/ref_main.md",
 			"Mimi API" => "ref/ref_API.md",
-			"Structures: Overview" => "ref/ref_structures_1_overview.md", 
-			"Structures: Definitions" => "ref/ref_structures_2_definitions.md", 
-			"Structures: Instances" => "ref/ref_structures_3_instances.md"
+			"Structures" => "ref/ref_structures.md", 
+			"Structures: Definitions" => "ref/ref_structures_definitions.md", 
+			"Structures: Instances" => "ref/ref_structures_instances.md"
 		],
 		"FAQ" => "faq.md",
 	],

docs/src/howto/howto_6.md

@@ -4,19 +4,21 @@ The release of Mimi v1.0.0 is a breaking release, necessitating the adaptation o
 
 This guide provides an overview of the steps required to get most models using the v0.9.5 API working with v1.0.0.  It is **not** a comprehensive review of all changes and new functionalities, but a guide to the minimum steps required to port old models between versions.  For complete information on the new version and its additional functionalities, see the full documentation.
 
-To port your model, we recommend you update to **Mimi v0.10.0**, which is identical to Mimi v1.0.0 **except** that it includes deprecation warnings for most breaking changes, instead of errors. This means that models written using Mimi v0.9.5 will, in most cases, run successfully under Mimi v0.10.0 and things that will cause errors in v1.0.0 will throw deprecation warnings. your changes. These can guide Thus a good workflow would be:
+## Workflow Advice
+
+To port your model, we recommend you update to **Mimi v0.10.0**, which is identical to Mimi v1.0.0 **except** that it includes deprecation warnings for most breaking changes, instead of errors. This means that models written using Mimi v0.9.5 will, in most cases, run successfully under Mimi v0.10.0 and things that will cause errors in v1.0.0 will throw deprecation warnings. These can guide your changes, and thus a good workflow would be:
 
 1) Update your environment to use Mimi v0.10.0 with 
-```julia
-pkg> add Mimi#v0.10.0
-```
+    ```julia
+    pkg> add Mimi#v0.10.0
+    ```
 2) Read through this guide to get a sense for what has changed
 3) Run your code and incrementally update it, using the deprecation warnings as guides for what to change and the instructions in this guide as explanations, until no warnings are thrown and you have changed anything relevant to your code that is explained in this gude.
-5) Update to Mimi v1.0.0 with the following code, which will update Mimi to it's latest version, v1.0.0
-```julia
-pkg> free Mimi
-```
-6) Run your model! Things should run smoothly now. If not double check the guide, and feel free to reach out on the forum with any questions. Also, if you are curious about the reasons behind a change, just ask!
+4) Update to Mimi v1.0.0 with the following code, which will update Mimi to it's latest version, v1.0.0
+    ```julia
+    pkg> free Mimi
+    ```
+5) Run your model! Things should run smoothly now. If not double check the guide, and feel free to reach out on the forum with any questions. Also, if you are curious about the reasons behind a change, just ask!
 
 This guide is organized into a few main sections, each descripting an independent set of changes that can be undertaken in any order desired. 
 
@@ -33,9 +35,11 @@ This guide is organized into a few main sections, each descripting an independen
 #### Type-parameterization for Parameters
 
 *The Mimi Change:* 
+
 To be consistent with julia syntax, Mimi now uses bracketing syntax to type-parameterize `Parameter`s inside the `@defcomp` macro instead of double-colon syntax. h
 
 *The User Change:* 
+
 Where you previously indicated that the parameter `a` should be an `Int` with 
 ```julia
 @defcomp my_comp begin
@@ -56,9 +60,11 @@ end
 #### Integer Indexing
 
 *The Mimi Change:* 
+
 For safety, Mimi no longer allows indexing into `Parameter`s or `Varaible`s with the `run_timestep` function of the `@defcomp` macro with integers. Instead, this functionality is supported with two new types: `TimestepIndex` and `TimestepValue`. Complete details on indexing options can be found in How-to Guide 4: Work with Timesteps, Parameters, and Variables, but below we will describe the minimum steps to get your models working.
 
 *The User Change:* 
+
 Where you previously used integers to index into a `Parameter` or `Variable`, you should now use the `TimestepIndex` type.  For example, the code
 ```julia
 function run_timestep(p, v, d, t)
@@ -84,19 +90,22 @@ function run_timestep(p, v, d, t)
 end
 ```
 
-#### is_timestep and is_time
+#### `is_timestep` and `is_time`
 
 *The Mimi Change:* 
+
 For simplicity and consistency with the change above, Mimi no longer supports the `is_timestep` or `is_time` functions and has replaced this functionality with comparison operators combined with the afformentioned `TimestepValue` and `TimestepIndex` types.
 
 *The User Change:* 
+
 Any instance of the `is_timestep` function should be replaced with simple comparison with a `TimestepIndex` object ie. replace the logic `if is_timestep(t, 10) ...` with `if t == TimestepIndex(10) ...`.
 
 Any instance of the `is_time` function should be repalced with simple comparison with a `TimestepValue` object ie. replace the logic `if is_time(t, 2010) ...` with `if t == TimestepValue(2010) ...`.
 
 ## The set_param! Function
 
 *The Mimi Change:* 
+
 The `set_param!` method for setting a parameter value in a component now has the following signature:
 ```
 set_param!(m::Model, comp_name::Symbol, param_name::Symbol, ext_param_name::Symbol, val::Any)
@@ -117,6 +126,7 @@ set_param!(m::Model, comp_name::Symbol, param_name::Symbol, val::Any)
 This method creates a new external parameter called `param_name` in the model `m` (if that already exists, it errors), sets its value to `val`, and then connects the parameter `param_name` in component `comp_name` to this newly created external parameter.
 
 *The User Change:* 
+
 Any old code that uses the `set_param!` method with only 4 arguments (shortcut #2 shown above) will still work for setting parameters **if they are found in only one component** ... but if you have multiple components that have parameters with the same name, using the old 4-argument version of `set_param!` multiple times will cause an error. Instead, you need to determine what behavior you want across multiple components with parameters of the same name:
 - If you want parameters with the same name that are found in multiple components to have the _same_ value, use the 3-argument method:  `set_param!(m, :param_name, val)`. You only have to call this once and it will set the same value for all components with an unconnected parameter called `param_name`.
 - If you want different components that have parameters with the same name to have _different_ values, then you need to call the 5-argument version of `set_param!` individually for each parameter value, such as:
@@ -134,9 +144,11 @@ This updates the value of the external parameter called `ext_param_name` in the
 ## The replace_comp! Function
 
 *The Mimi Change:* 
+
 For simplicity, the `replace_comp!` function has been replaced with a method augmenting the julia Base `replace!` function.
 
-*The User Change:* 
+*The User Change:*
+
 Where you previously used
 ```julia
 replace_comp!(m, new, old)
@@ -149,17 +161,21 @@ replace!(m, old => new)
 ## Different-length Components 
 
 *The Mimi Change:* 
+
 Through Mimi v0.9.4, the optional keyword arguments `first` and `last` could be used to specify times for components that do not run for the full length of the model, like this: `add_comp!(mymodel, ComponentC; first=2010, last=2100)`. This functionality is still disabled, as it was starting in v0.9.5, and all components must run for the full length of the model's time dimension. This functionality may be re-implemented in a later version of Mimi.
 
 *The User Change:* 
+
 Refactor your model so that all components are the same length. You may use the `run_timestep` function within each component to dictate it's behavior in different timesteps, including doing no calculations for a portion of the full model runtime.
 
 ## Marginal Models
 
 *The Mimi Change:* 
+
 For clarity, the previously named `marginal` attribute of a Mimi `MarginalModel` has been renamed to `modified`.  Hence a `MarginalModel` is now described as a Mimi `Model` whose results are obtained by subtracting results of one `base` Model from those of another `marginal` Model that has a difference of `delta` with the signature:
 
 *The User Change:* 
+
 Any previous access to the `marginal` attribute of a `MarginalModel`, `mm` below, should be changed from 
 ```julia
 model = mm.marginal
@@ -173,9 +189,11 @@ model = mm.modified
 #### Results Access
 
 *The Mimi Change:* 
+
 For clarity of return types, Mimi no longer supports use of square brackets (a shortcut for julia Base `getindex`) to access the results of a Monte Carlo analysis, which are stored in the `SimulationInstance`.  Instead, access to resulst is supported with the `getdataframe` function, which will return the results in the same type and format as the square bracket method used to return.
 
 *The User Change:* 
+
 Results previously obtained with 
 ```julia
 results = si[:grosseconomy, :K]
@@ -187,9 +205,11 @@ results = getdataframe(si, :grosseconomy, :K)
 #### Simulation Definition Modification Functions
 
 *The Mimi Change:* 
+
 For consistency with julia syntax rules, the small set of unexported functions available to modify an existing `SimulationDefinition` have been renamed, moving from a camel case format to an underscore-based format as follows.
 
 *The User Change:* 
+
 Replace your functions as follows.
 
 - `deleteRV!` --> `delete_RV!`
@@ -203,7 +223,9 @@ Replace your functions as follows.
 ## Composite Components (optional)
 
 *The Mimi Change:* 
+
 The biggest functionality **addition** of Mimi v1.0.0 is the inclusion of composite components.  Prior versions of Mimi supported only "flat" models, i.e., with one level of components. This new version supports mulitple layers of components, with some components being "final" or leaf components, and others being "composite" components which themselves contain other leaf or composite components. This approach allows for a cleaner organization of complex models, and allows the construction of building blocks that can be re-used in multiple models.
 
 *The User Change:* 
+
 All previous models are considered "flat" models, i.e. they have only one level of components, and do **not** need to be converted into multiple layer models to run. Thus this addition does not mean users need to alter their models, but we encourage you to check out the other documentation on composite components to learn how you can enhance your current models and built better onces in the future!

docs/src/howto/howto_main.md

@@ -1,36 +1,24 @@
 # How-to Guides Introduction
 
-The following how-to guides provide steps to carry out several common real-world problems that Mimi is targeted at solving. They are a bit less detailed than the tutorials, and are thus targeted at a user with some level of experience with Mimi (likely obtained through moving through some or all of the tutorials). 
+The following how-to guides provide steps to work through several common real-world problems that Mimi is targeted at solving. They are a bit less detailed than the tutorials, and are thus targeted at a user with some level of experience with Mimi (likely obtained through moving through some or all of the tutorials). 
 
 If you find a bug in these guides, or have a clarifying question or suggestion, please reach out via Github Issues or our [Mimi Framework forum](https://forum.mimiframework.org).  We welcome your feedback.
 
 ## Available How-to Guides
 
-1. **Construct and Run a Flat Model**
+1. [How-to Guide 1: Construct and Run a Model](@ref) 
 
-   [How-to Guide 1: Construct and Run a Model](@ref) 
 
+2. [How-to Guide 2: View and Explore Model Results](@ref) 
 
-2. **View and Explore Model Results**
 
-   [How-to Guide 2: View and Explore Model Results](@ref) 
+3. [How-to Guide 3: Conduct Sensitivity Analysis](@ref)
 
 
-3. **Conduct Sensitivity Analysis**
+4. [How-to Guide 4: Work with Timesteps, Parameters, and Variables](@ref)
 
-    [How-to Guide 3: Conduct Sensitivity Analysis](@ref)
 
+5. [How-to Guide 5: Port to Mimi v0.5.0](@ref)
 
-4. **Work with Timesteps, Parameters, and Variables**
 
-    [How-to Guide 4: Work with Timesteps, Parameters, and Variables](@ref)
-
-
-5. **Port to Mimi v0.5.0**
-
-    [How-to Guide 5: Port to Mimi v0.5.0](@ref)
-
-
-6. **Port to Mimi v1.0.0**
-
-    [How-to Guide 6: Port from (>=) Mimi v0.5.0 to Mimi v1.0.0](@ref)
+6. [How-to Guide 6: Port from (>=) Mimi v0.5.0 to Mimi v1.0.0](@ref)

docs/src/howto_advanced/howto_adv_main.md

@@ -1,16 +1,13 @@
 # Advanced How-to Guides Introduction
 
-The following how-to guides provide steps to carry out more specified and advanced real-world problems that Mimi can solve. They are less detailed than the tutorials, and are thus targeted at a user with some level of experience with Mimi (likely obtained through moving through some or all of the tutorials). 
+The following how-to guides provide steps to work through more specified and advanced real-world problems that Mimi can solve. They are less detailed than the tutorials, and are thus targeted at a user with some level of experience with Mimi (likely obtained through moving through some or all of the tutorials). 
 
 If you find a bug in these guides, or have a clarifying question or suggestion, please reach out via Github Issues or our [Mimi Framework forum](https://forum.mimiframework.org).  We welcome your feedback.
 
 ## Available Advanced How-to Guides
 
-- **Build and Init Functions**
+- [Advanced How-to Guide: Build and Init Functions](@ref) describes the innerworkings of the `build` and `init` functions which may be useful in special cases.
 
-    [Advanced How-to Guide: Build and Init Functions](@ref) describes the innerworkings of the `build` and `init` functions which may be useful in special cases.
 
-- **Using Datum References**
-
-   [Advanced How-to Guide: Using Datum References](@ref) describes how to use references to datum, or more specifically components, for scenarios where such use improves code brevity and understandability.
+- [Advanced How-to Guide: Using Datum References](@ref) describes how to use references to datum, or more specifically components, for scenarios where such use improves code brevity and understandability.
 

docs/src/index.md

@@ -4,7 +4,7 @@
 
 Mimi is a [Julia](http://julialang.org) package that provides a component model for [integrated assessment models](https://en.wikipedia.org/wiki/Integrated_assessment_modelling), as described in detail on the [Mimi Framework Homepage](https://www.mimiframework.org).
 
-The following documentation is organized into the following four sections, roughly adhering to the [Divio documentation system](https://documentation.divio.com) guidelines. For insights into the goals of each of these sections, please refer to the Divio documentation.
+The documentation is organized into the following four sections, roughly adhering to the [Divio documentation system](https://documentation.divio.com) guidelines. For insights into the goals of each of these documentation categories, please refer to the Divio documentation.
 
 1. Tutorials
 2. How-to Guides
@@ -13,11 +13,11 @@ The following documentation is organized into the following four sections, rough
 
 ## Getting started
 
-We aim to provide assistance to users of all different experience levels, starting with first-time users. If this is your first time using Mimi, we recommend you begin with the Tutorials. In addition, looking through the code at the links below to various existing models based on Mimi can be instructive. 
+We aim to assist users of all different experience levels, starting with first-time users. If this is your first time using Mimi, we recommend you begin with the Tutorials. In addition, looking through the code at the links below to various existing models based on Mimi can be instructive. 
 
 The first step for any user includes installation of julia and Mimi, as well as optionally adding the Mimi Registry. See the first tutorial for instructions on these tasks.
 
-Finally, when in doubt, ask your question on the [Mimi Framework forum](https://forum.mimiframework.org) or post an [Issue](https://github.com/mimiframework/Mimi.jl/issues) to the Github repository if you have a specific request for the development team.   Don't be shy about either option, we would much prefer to be inundated with lots of questions and help people out than people give up on Mimi!
+Finally, when in doubt, ask your question on the [Mimi Framework forum](https://forum.mimiframework.org) or post an [Issue](https://github.com/mimiframework/Mimi.jl/issues) to the Github repository, the latter being especially pertintent if you have a specific request for the development team.   Don't be shy about either option, we would much prefer to be inundated with lots of questions and help people out than people give up on Mimi!
 
 ## Models using Mimi