Make Consistent API and Put content of examples/main.jl in README

[rjplevin]

I was just trying to run the various model packages and would like to suggest that we put the contents of each model's examples/main.jl directly in the README, to facilitate cut & paste. They all look like this:

using Mimi
using MimiFUND

m = getfund()
run(m)
explore(m)

I'd also prefer a consistent API across the models. So instead of getfund(), getrice(), etc., we would define MimiFUND.getmodel() and MimiRICE2010.getmodel(). Of course, if you use only one model at a time, the exported getmodel() would suffice, without module specification.

[corakingdon]

I also would prefer that ModelName.getmodel() were the standard API

[davidanthoff]

Yes, it would be great to get a more standard API there! I think we should probably wait until the composite component stuff is there, though. Once that is the case, we will have multiple models per package (say one normal one, and one SCC one), and it would be nice to also have a standard API to e.g. enumerate what models exist in a package etc.

[rjplevin]

No reason not to start thinking concretely about this, right? How about an API like this:

# Get a Mimi.Model. With no args, gets the default model. If variant !== nothing,
# get that `variant` of the model. Keyword args are pkg-specific.
PkgName.getmodel(variant::Union{Nothing, Symbol}=nothing; kwargs...)::Mimi.Model

# Introspection methods

# Return a string describing the given `getmodel` keyword. Throw an error
# if `name` is not a known option.
PkgName.model_option(name::Symbol)::String

# Return a dict mapping all `getmodel` keywords to short description strings.
PkgName.model_options()::Dict{Symbol, String}

# Return a string describing the given `getmodel` variant
PkgName.model_variant(name::Symbol)::String

# Return a dict mapping all `getmodel` variants to short description strings.
PkgName.model_variants()::Dict{Symbol, String}

[davidanthoff]

We could use some time tomorrow to chat about designs?

[rjplevin]

Sure, that would be good. As I mentioned, all the models seems to work with the composite branch. Next step would be to convert one or more to actually use composites, as I expect that will reveal some necessary changes. But we're very close...

[corakingdon]

What I am implementing for milestone v0.9.0 is the following:

PkgName.getmodel()
PkgName.computeSCC(m::Model = getmodel(); kwargs...)
PkgName.getMarginalModel(m::Model = getmodel(); kwargs...)    # is this name okay? or should it be get_marginal_model
PkgName.computeSCC(mm::MarginalModel; kwargs...)

And in the keyword arguments for the last three functions, the emissionyear parameter is mandatory (i.e. calling it with nothing throws an error and asks the user to specify an emission year) and the rest of the arguments have default values. The rest of the arguments are different for the different models, but they will all need to have an emissionyear parameter. Is that the name we want to use across all models? Or should it just be year?

I started this for MimiFUND here if you want to take a look: fund-model/MimiFUND.jl#18

[rjplevin]

I would prefer not to introduce camel case, so I'd name these:
getmodel, compute_scc (or compute_SCC), and get_marginal_model. I might even prefer get_model for consistency with get_marginal_model.

[rjplevin]

I would prefer pulse_year to emissionyear, since there are emissions in all years.
Given that these last 3 methods are for a specific purpose, having the same keywd arg makes sense. It's not a general purpose API.

[corakingdon]

@davidanthoff thoughts on these names?

• getmodel() or get_model()
• computeSCC() or compute_scc() or compute_SCC()
• getMarginalModel() or get_marginal_model() on this one, I usually agree on avoiding camel case, but I was originally thinking of making an exception since MarginalModel is a Mimi type that has those capitals, but I'm realizing now that the "first user" does not care or know about that so it probably doesn't make much sense