From 224e3e891a6b94f6ce24c282661d465598be689e Mon Sep 17 00:00:00 2001 From: lrennels Date: Sat, 9 Mar 2019 16:47:19 -0800 Subject: [PATCH] Update tutorials using Mimi registry syntax --- README.md | 15 +++++++++++++ docs/src/index.md | 17 +++++++++++++++ docs/src/tutorials/tutorial_1.md | 30 +++++++++++--------------- docs/src/tutorials/tutorial_2.md | 33 +++++++++-------------------- docs/src/tutorials/tutorial_3.md | 4 ++-- docs/src/tutorials/tutorial_main.md | 16 +++++++++++++- 6 files changed, 71 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index d67bc0955..95d680ba6 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,21 @@ Mimi is an installable package. To install Mimi, use the following: Pkg.add("Mimi") ```` +## Mimi Registry + +Several models currently use the Mimi framework, as listed in the section below. For convenience, several models are registered in the [MimiRegistry](https://github.com/anthofflab/Mimi.jl), and operate as julia packages. To use this feature, you first need to connect your julia installation with the central Mimi registry of Mimi models. This central registry is like a catalogue of models that use Mimi that is maintained by the Mimi project. To add this registry, run the following command at the julia package REPL: + +```julia +pkg> registry add https://github.com/mimiframework/MimiRegistry.git +``` + +You only need to run this command once on a computer. + +From there you may add any of the registered packages, such as MimiRICE2010.jl by running the following command at the julia package REPL: + +```julia +pkg> add MimiRICE2010 +``` ## Models using Mimi * [FUND.jl](https://github.com/davidanthoff/fund.jl) (currently in beta) diff --git a/docs/src/index.md b/docs/src/index.md index a7bd38353..b5393f08e 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -14,6 +14,23 @@ Pkg.add("Mimi") For more complete setup instructions, follow the [Installation Guide](@ref). + +## Mimi Registry + +Several models currently use the Mimi framework, as listed in the section below. For convenience, several models are registered in the [MimiRegistry](https://github.com/anthofflab/Mimi.jl), and operate as julia packages. To use this feature, you first need to connect your julia installation with the central Mimi registry of Mimi models. This central registry is like a catalogue of models that use Mimi that is maintained by the Mimi project. To add this registry, run the following command at the julia package REPL: + +```julia +pkg> registry add https://github.com/mimiframework/MimiRegistry.git +``` + +You only need to run this command once on a computer. + +From there you may add any of the registered packages, such as MimiRICE2010.jl by running the following command at the julia package REPL: + +```julia +pkg> add MimiRICE2010 +``` + ## Models using Mimi * [FUND.jl](https://github.com/davidanthoff/fund.jl) (currently in beta) diff --git a/docs/src/tutorials/tutorial_1.md b/docs/src/tutorials/tutorial_1.md index 123e2f784..a738d3ad2 100644 --- a/docs/src/tutorials/tutorial_1.md +++ b/docs/src/tutorials/tutorial_1.md @@ -4,45 +4,39 @@ This tutorial walks through the steps to download, run, and view the output of a Working through the following tutorial will require: -- [Julia v1.0.0](https://julialang.org/downloads/) or higher -- [Mimi v0.6.0](https://github.com/mimiframework/Mimi.jl) +- [Julia v1.1.0](https://julialang.org/downloads/) or higher +- [Mimi v0.8.0](https://github.com/mimiframework/Mimi.jl) - [Git](https://git-scm.com/downloads) and [Github](https://github.com) If you have not yet prepared these, go back to the main tutorial page and follow the instructions for their download. ### Step 1. Download FUND -The first step in this process is downloading the FUND model. First, open your command line interface and navigate to the folder where you would like to 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 to connect your julia installation with the central Mimi registry of Mimi models -``` -cd() # directory-path is a placeholder for the string describing your desired file path +```julia +pkg> registry add https://github.com/mimiframework/MimiRegistry.git ``` -Next, clone the FUND repository from Github, enter the repository, and checkout the `next` branch, which holds the Julia version of FUND. - +You simply need to add the FUND model with ``` -git clone https://github.com/fund-model/fund.git -cd("fund") -git checkout next +add MimiFUND ``` -You have now successfully downloaded FUND to your local machine. ### Step 2. Run FUND The next step is to run FUND. If you wish to first get more aquainted with the model itself, take a look at the provided online documentation. -In order to run FUND, you will need to open a Julia REPL (here done with the alias `julia`) and navigate to the source code folder, labeled `src`. +In order to run FUND, you will need to have the packages `Distributions` and `StatsBase` installed, and if not do so by entering [Pkg mode](https://docs.julialang.org/en/v1/stdlib/Pkg/index.html) by typing `]`, and then `add StatsBase` and `add Distributions`. + +Now open a julia REPL and type ``` -Julia -cd() # fund-directory-path is a placeholder for the string describing your the file path of the downloaded `fund` folder from Step 1. +using MimiFUND ``` - -Next, run the main fund file `fund.jl` (make sure to have the packages `Distributions` and `StatsBase` installed, and if not do so by entering [Pkg mode](https://docs.julialang.org/en/v1/stdlib/Pkg/index.html) by typing `]`, and then `add StatsBase` and `add Distributions`. This file defines a new [module](https://docs.julialang.org/en/v1/manual/modules/index.html) called `Fund`, which exports the function `getfund`, a function that returns a version of fund allowing for different user specifications. Note that in order to allow access to the module, we must call `using .Fund`, where `.Fund` is a shortcut for `Main.Fund`, since the `Fund` module is nested inside the `Main` module. After creating the model `m`, simply run the model using the `run` function. +to access the public API to FUND, which currently includes the function `getfund`, a function that returns a version of fund allowing for different user specifications. ``` -include("src/fund.jl") -using .Fund m = getfund() run(m) ``` diff --git a/docs/src/tutorials/tutorial_2.md b/docs/src/tutorials/tutorial_2.md index 3a547b3da..a04592c3e 100644 --- a/docs/src/tutorials/tutorial_2.md +++ b/docs/src/tutorials/tutorial_2.md @@ -6,13 +6,13 @@ This tutorial walks through the steps to modify an existing model. There are se Working through the following tutorial will require: -- [Julia v1.0.0](https://julialang.org/downloads/) or higher -- [Mimi v0.6.0](https://github.com/mimiframework/Mimi.jl) +- [Julia v1.1.0](https://julialang.org/downloads/) or higher +- [Mimi v0.8.0](https://github.com/mimiframework/Mimi.jl) - [Git](https://git-scm.com/downloads) and [Github](https://github.com) If you have not yet prepared these, go back to the main tutorial page and follow the instructions for their download. -Futhermore, this tutorial uses the [DICE](https://github.com/anthofflab/mimi-dice-2010.jl) model as an example. Downloading `DICE` uses similar steps to those described for `FUND` in Tutorial 1 Steps 1 and 2, but are repeated in in Step 1 for clarity. +Futhermore, this tutorial uses the [DICE](https://github.com/anthofflab/mimi-dice-2010.jl) model as an example. Downloading `DICE` uses similar steps to those described for `FUND` in Tutorial 1 Steps 1 and 2. ## Introduction @@ -40,37 +40,24 @@ If you wish to alter connections within an existing model, [`disconnect_param!`] ### Step 1. Download DICE -The first step in this process is downloading the DICE model. First, open your command line interface and navigate to the folder where you would like to download DICE. +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 to connect your julia installation with the central Mimi registry of Mimi models +```julia +pkg> registry add https://github.com/mimiframework/MimiRegistry.git ``` -cd() # directory-path is a placeholder for the string describing your desired file path -``` - -Next, clone the DICE repository from Github, and enter the repository. +You simply need to add the DICE2010 model with ``` -git clone https://github.com/anthofflab/mimi-dice-2010.jl.git -cd("mimi-dice-2010.jl") - +add MimiDICE2010 ``` You have now successfully downloaded DICE to your local machine. ### Step 2. Run DICE -The next step is to run DICE. If you wish to first get more aquainted with the model itself, take a look at the provided online documentation. - -In order to run DICE, you will need to open a Julia REPL (here done witht the alias `julia`) and navigate to the source code folder, labeled `src`. - -``` -Julia -cd() # is a placeholder for the string describing your the file path of the downloaded `dice-2010` folder from Step 1. -``` - -Next, run the main fund file `dice2010.jl`. This file defines a new [module](https://docs.julialang.org/en/v1/manual/modules/index.html) called `Dice2010`, which exports the function `construct_dice`, a function that returns a version of dice allowing for user specification of parameters. Note that in order to allow access to the module, we must call `using .Dice2010`, where `.Dice2010` is a shortcut for `Main.Dice2010`, since the `Dice2010` module is nested inside the `Main` module. After creating the model `m`, simply run the model using the `run` function. +The next step is to run DICE. If you wish to first get more aquainted with the model itself, take a look at the provided online documentation. Now run DICE using the provided API for the package: ``` -include("src/dice2010.jl") -using .Dice2010 +using MimiDICE2010 m = construct_dice() run(m) ``` diff --git a/docs/src/tutorials/tutorial_3.md b/docs/src/tutorials/tutorial_3.md index f98c3c90c..307b7b4b1 100644 --- a/docs/src/tutorials/tutorial_3.md +++ b/docs/src/tutorials/tutorial_3.md @@ -6,8 +6,8 @@ While we will walk through the code step by step below, the full code for implem Working through the following tutorial will require: -- [Julia v1.0.0](https://julialang.org/downloads/) or higher -- [Mimi v0.6.0](https://github.com/mimiframework/Mimi.jl) +- [Julia v1.1.0](https://julialang.org/downloads/) or higher +- [Mimi v0.8.0](https://github.com/mimiframework/Mimi.jl) - [Git](https://git-scm.com/downloads) and [Github](https://github.com) If you have not yet prepared these, go back to the main tutorial page and follow the instructions for their download. diff --git a/docs/src/tutorials/tutorial_main.md b/docs/src/tutorials/tutorial_main.md index 55310a25d..852506eec 100644 --- a/docs/src/tutorials/tutorial_main.md +++ b/docs/src/tutorials/tutorial_main.md @@ -47,7 +47,21 @@ To use the following tutorials, follow the steps below. pkg> add Mimi ``` -We also recommend that you frequently update your packages and requirements using the `update` command, which can be abbreviated `up`: +4. To access the models in the [MimiRegistry](https://github.com/anthofflab/Mimi.jl), you first need to connect your julia installation with the central Mimi registry of Mimi models. This central registry is like a catalogue of models that use Mimi that is maintained by the Mimi project. To add this registry, run the following command at the julia package REPL: + +```julia +pkg> registry add https://github.com/mimiframework/MimiRegistry.git +``` + +You only need to run this command once on a computer. + +From there you will be add any of the registered packages, such as MimiRICE2010.jl by running the following command at the julia package REPL: + +```julia +pkg> add MimiRICE2010 +``` + +5. We also recommend that you frequently update your packages and requirements using the `update` command, which can be abbreviated `up`: ``` pkg> up ```