Environment

The environment model provides a collection of parameter functions designed for coupling to other models. More...

Collaboration diagram for Environment:

Classes
struct	Utopia::Models::Environment::BaseEnvParam
	Base type for environment parameter. More...
struct	Utopia::Models::Environment::DummyEnvParam
	Dummy type for environment parameter. More...
struct	Utopia::Models::Environment::BaseEnvCellState
	Base type for environment cell states. More...
struct	Utopia::Models::Environment::DummyEnvCellState
	Dummy type for environment cell states. More...
class	Utopia::Models::Environment::Environment< EnvParam, EnvCellState, standalone >
	The Environment model provides a non-uniform, dynamic parameter background. More...
struct	Utopia::Models::Environment::FuncBundle::FuncBundle< Func, Time >
	A bundle wrapping a (iterative) function with metadata. More...
struct	Utopia::Models::Environment::FuncBundle::ParamFuncBundle< Func, Time >
	A bundle wrapping a (iterative) function with metadata. More...
struct	Utopia::Models::Environment::FuncBundle::RuleFuncBundle< RuleFunc, Time, CellContainer >
	A bundle wrapping a (rule-)function with metadata. More...

Typedefs
using	Utopia::Models::Environment::ModelTypes = Utopia::ModelTypes<>
	Type helper to define types used by the model.

Enumerations
enum class	Utopia::Models::Environment::ValMode { Utopia::Models::Environment::ValMode::Set , Utopia::Models::Environment::ValMode::Add }
	Value calculation mode. More...

Functions
template<typename EnvModel , class EnvParamFunc = typename EnvModel::EnvParamFunc>
EnvParamFunc	Utopia::Models::Environment::ParameterFunctionCollection::epf_increment (const EnvModel &model, const std::string param_name, const Config &cfg)
	Creates a rule function for incrementing parameter values.
template<typename EnvModel , class EnvParamFunc = typename EnvModel::EnvParamFunc>
EnvParamFunc	Utopia::Models::Environment::ParameterFunctionCollection::epf_random (const EnvModel &model, const std::string &param_name, const Config &cfg)
	Creates a rule function for random parameter values.
template<typename EnvModel , class EnvParamFunc = typename EnvModel::EnvParamFunc>
EnvParamFunc	Utopia::Models::Environment::ParameterFunctionCollection::epf_rectangular (const EnvModel &model, const Config &cfg)
	Creates a rule function for rectangular function like parameter values.
template<typename EnvModel , class EnvParamFunc = typename EnvModel::EnvParamFunc>
EnvParamFunc	Utopia::Models::Environment::ParameterFunctionCollection::epf_set (const EnvModel &, const Config &cfg)
	Creates a rule function for setting a parameter value.
template<typename EnvModel , class EnvParamFunc = typename EnvModel::EnvParamFunc>
EnvParamFunc	Utopia::Models::Environment::ParameterFunctionCollection::epf_sinusoidal (const EnvModel &model, const Config &cfg)
	Creates a rule function for sinusoidal parameter values.
template<typename EnvModel , class EnvStateFunc = typename EnvModel::EnvStateFunc>
std::pair< EnvStateFunc, Update >	Utopia::Models::Environment::StateFunctionCollection::esf_noise (const EnvModel &model, const std::string &param_name, const Config &cfg)
	Creates a rule function for noisy parameter values.
template<typename EnvModel , typename Extent , class EnvStateFunc = typename EnvModel::EnvStateFunc>
std::pair< EnvStateFunc, Update >	Utopia::Models::Environment::StateFunctionCollection::esf_slope (const EnvModel &, const std::string &param_name, const Config &cfg, const Extent &extent)
	Creates a rule function for spatially linearly parameter values.
template<typename EnvModel , class EnvStateFunc = typename EnvModel::EnvStateFunc>
std::pair< EnvStateFunc, Update >	Utopia::Models::Environment::StateFunctionCollection::esf_steps (const EnvModel &, const std::string &param_name, const Config &cfg)
	Creates a rule function for spatial steps in the parameter values.
template<typename EnvModel , class EnvStateFunc = typename EnvModel::EnvStateFunc>
std::pair< EnvStateFunc, Update >	Utopia::Models::Environment::StateFunctionCollection::esf_uniform (const EnvModel &, const std::string &param_name, const Config &cfg)
	Creates a rule function for spatially uniform parameter values.
ValMode	Utopia::Models::Environment::extract_val_mode (const DataIO::Config &cfg, const std::string &context)
	Given a configuration node, extract the value mode.
template<typename Time >
std::pair< bool, std::set< Time > >	Utopia::Models::Environment::extract_times (const DataIO::Config &cfg)
template<typename Time >
std::tuple< bool, bool, std::set< Time > >	Utopia::Models::Environment::extract_times_and_initialization (const DataIO::Config &cfg)
template<typename Time >
Time	Utopia::Models::Environment::extract_time_start (const DataIO::Config &cfg)
	Given a configuration, extracts the time of first function invocation.

Detailed Description

The environment model provides a collection of parameter functions designed for coupling to other models.

For details on how this is to be used, consult the actual model documentation. The doxygen documentation here provides merely the API reference and information on the available parameters for each of the environment functions.

Typedef Documentation

ModelTypes

using Utopia::Models::Environment::ModelTypes = typedef Utopia::ModelTypes<>

Type helper to define types used by the model.

Enumeration Type Documentation

ValMode

enum class Utopia::Models::Environment::ValMode

strong

Value calculation mode.

Enumerator
Set	Set a value, discarding the current state.
Add	Add the new value to the existing value.

                   {
    Set,
 
    Add
};

Function Documentation

epf_increment()

template<typename EnvModel , class EnvParamFunc = typename EnvModel::EnvParamFunc>

EnvParamFunc Utopia::Models::Environment::ParameterFunctionCollection::epf_increment	(	const EnvModel &	model,
		const std::string	param_name,
		const Config &	cfg
	)

Creates a rule function for incrementing parameter values.

Parameters

param_name	The parameter to attach this environment function to
cfg	Configuration for this environment function. Allows the following arguments: times: Sequence of time points at which to invoke this. if None, always incrementing value: The incrementor invoke_at_initialization: Whether to invoke at initialization. Default is False

{
    const auto value = get_as<double>("value", cfg);
    EnvParamFunc epf = [&model, param_name, value] () mutable
    {
        return model.get_parameter(param_name) + value;
    };
 
    return epf;
}

epf_random()

template<typename EnvModel , class EnvParamFunc = typename EnvModel::EnvParamFunc>

EnvParamFunc Utopia::Models::Environment::ParameterFunctionCollection::epf_random	(	const EnvModel &	model,
		const std::string &	param_name,
		const Config &	cfg
	)

Creates a rule function for random parameter values.

Parameters

param_name

The parameter to attach this environment function to

cfg

Configuration for this environment function. Allows the following arguments: mode: set (default) or add times: Sequence of time points at which to invoke this distribution: The distribution type. For each value below, the corresponding additional parameters are required in cfg: normal: mean and stddev poisson: mean exponential: lambda uniform: interval (length 2 array) uniform_int: interval (length 2 array)

{
    const auto mode = extract_val_mode(cfg, "random");
    const auto distribution = get_as<std::string>("distribution", cfg);
 
    // Depending on chosen distribution, construct it and build a rule
    // function using a reference to the newly created one...
    if (distribution == "normal") {
        const auto mean = get_as<double>("mean", cfg);
        const auto stddev = get_as<double>("stddev", cfg);
        std::normal_distribution<> dist(mean, stddev);
 
        return build_rng_env_param_func(model, std::move(dist), param_name,
                                        mode);
    }
    else if (distribution == "poisson") {
        const auto mean = get_as<double>("mean", cfg);
        std::poisson_distribution<> dist(mean);
 
        return build_rng_env_param_func(model, std::move(dist), param_name,
                                        mode);
    }
    else if (distribution == "exponential") {
        const auto lambda = get_as<double>("lambda", cfg);
        std::exponential_distribution<> dist(lambda);
 
        return build_rng_env_param_func(model, std::move(dist), param_name,
                                        mode);
    }
    else if (distribution == "uniform_int") {
        auto interval = get_as<std::array<int, 2>>("interval", cfg);
        std::uniform_int_distribution<> dist(interval[0], interval[1]);
 
        return build_rng_env_param_func(model, std::move(dist), param_name,
                                        mode);
    }
    else if (distribution == "uniform_real" or distribution == "uniform") {
        auto interval = get_as<std::array<double, 2>>("interval", cfg);
        std::uniform_real_distribution<> dist(interval[0], interval[1]);
 
        return build_rng_env_param_func(model, std::move(dist), param_name,
                                        mode);
    }
    else {
        throw std::invalid_argument("No method implemented to resolve "
            "noise distribution '" + distribution + "'! Valid options: "
            "normal, poisson, uniform_int, uniform_real.");
    }
};

epf_rectangular()

template<typename EnvModel , class EnvParamFunc = typename EnvModel::EnvParamFunc>

EnvParamFunc Utopia::Models::Environment::ParameterFunctionCollection::epf_rectangular	(	const EnvModel &	model,
		const Config &	cfg
	)

Creates a rule function for rectangular function like parameter values.

Rectangular shaped parameters.

Parameters

param_name

The parameter to attach this environment function to

cfg

Configuration for this environment function. Allows the following arguments: times: Sequence of time points at which to invoke this. if None, always setting offset: The minimum value. Optional, default 0. amplitude: The amplitude above minimum value period: The period time_in_max: The number of steps in max value. Optional, default half period. phase: The phase at first invocation in fraction of period length. E.g.: 0.5 for initialization at half period. Optional, default 0 equiv. in high value.

{
    using Time = typename EnvModel::Time;
 
    double min_value = get_as<double>("offset", cfg, 0.);
    double max_value = get_as<double>("amplitude", cfg) + min_value;
    Time period = get_as<Time>("period", cfg);
    Time time_in_max = get_as<Time>("time_in_max", cfg, period / 2.);
    double phase = get_as<double>("phase", cfg, 0) * period;
 
    // Check parameter
    if (time_in_max > period) {
        throw std::invalid_argument("The `time_in_max` argument cannot be "
                    "larger than the `period` argument in rectangular "
                    "environment parameter function!");
    }
    if (phase < 0 or phase > period) {
        throw std::invalid_argument("The `phase` argument was not in interval "
                    "[0., 1.]!");
    }
 
    // get starting time
    Time time_start = extract_time_start<Time>(cfg);
 
    // Build function
    EnvParamFunc epf = [&model, max_value, min_value,
                        period, time_in_max, phase, time_start] () mutable
    {
        auto time = (model.get_time()+1 - time_start) % period;
        if (time >= phase and time < time_in_max + phase) {
            return max_value;
        }
        return min_value;
    };
 
    return epf;
}

epf_set()

template<typename EnvModel , class EnvParamFunc = typename EnvModel::EnvParamFunc>

EnvParamFunc Utopia::Models::Environment::ParameterFunctionCollection::epf_set	(	const EnvModel &	,
		const Config &	cfg
	)

Creates a rule function for setting a parameter value.

Parameters

param_name	The parameter to attach this environment function to
cfg	Configuration for this environment function. Allows the following arguments: times: Sequence of time points at which to invoke this. if None, always setting value: The new value invoke_at_initialization: Whether to invoke at initialization. Default is False

{
    const auto value = get_as<double>("value", cfg);
    EnvParamFunc epf = [value] () mutable
    {
        return value;
    };
 
    return epf;
}

epf_sinusoidal()

template<typename EnvModel , class EnvParamFunc = typename EnvModel::EnvParamFunc>

EnvParamFunc Utopia::Models::Environment::ParameterFunctionCollection::epf_sinusoidal	(	const EnvModel &	model,
		const Config &	cfg
	)

Creates a rule function for sinusoidal parameter values.

Parameters

param_name

The parameter to attach this environment function to

cfg

Configuration for this environment function. Allows the following arguments: times: Sequence of time points at which to invoke this. if None, always setting period: The period of the sinus amplitude: The amplitude phase: The phase shift at the point of first invokation. In multiples of pi. 1 = pi or 180 degree shift. Optional, default 0. offset: Offset of the mean value over the full period. Optional, default 0.

Note

Cannot be invoked at initialization.

{
    using Time = typename EnvModel::Time;
 
    const auto period = get_as<double>("period", cfg);
    const auto amplitude = get_as<double>("amplitude", cfg);
    double phase = 0;
    if (cfg["phase"]) {
        phase = get_as<double>("phase", cfg);
    }
    double offset = 0.;
    if (cfg["offset"]) {
        offset = get_as<double>("offset", cfg);
    }
 
    // get starting time
    Time time_start = extract_time_start<Time>(cfg);
 
    EnvParamFunc epf = [&model, period, amplitude,
                        phase, offset, time_start] () mutable
    {
        double x = (model.get_time() + 1 - time_start)/period * 2*M_PI;
        return offset + amplitude * sin(x + phase * M_PI);
    };
 
    return epf;
}

esf_noise()

template<typename EnvModel , class EnvStateFunc = typename EnvModel::EnvStateFunc>

std::pair< EnvStateFunc, Update > Utopia::Models::Environment::StateFunctionCollection::esf_noise	(	const EnvModel &	model,
		const std::string &	param_name,
		const Config &	cfg
	)

Creates a rule function for noisy parameter values.

Parameters

param_name

The parameter to attach this environment function to

cfg

Configuration for this environment function. Allows the following arguments: mode: set (default) or add times: Sequence of time points at which to invoke this distribution: The distribution type. For each value below, the corresponding additional parameters are required in cfg: normal: mean and stddev poisson: mean exponential: lambda uniform: interval (length 2 array) uniform_int: interval (length 2 array)

{
    const auto mode = extract_val_mode(cfg, "noise");
    const auto distribution = get_as<std::string>("distribution", cfg);
 
    // Depending on chosen distribution, construct it and build a rule
    // function using a reference to the newly created one...
    if (distribution == "normal") {
        const auto mean = get_as<double>("mean", cfg);
        const auto stddev = get_as<double>("stddev", cfg);
        std::normal_distribution<> dist(mean, stddev);
 
        auto esf = build_rng_env_state_func(model, std::move(dist), param_name,
                                            mode);
        return {esf, Update::sync};
    }
    else if (distribution == "poisson") {
        const auto mean = get_as<double>("mean", cfg);
        std::poisson_distribution<> dist(mean);
 
        auto esf = build_rng_env_state_func(model, std::move(dist), param_name,
                                            mode);
        return {esf, Update::sync};
    }
    else if (distribution == "exponential") {
        const auto lambda = get_as<double>("lambda", cfg);
        std::exponential_distribution<> dist(lambda);
 
        auto esf = build_rng_env_state_func(model, std::move(dist), param_name,
                                            mode);
        return {esf, Update::sync};
    }
    else if (distribution == "uniform_int") {
        auto interval = get_as<std::array<int, 2>>("interval", cfg);
        std::uniform_int_distribution<> dist(interval[0], interval[1]);
 
        auto esf = build_rng_env_state_func(model, std::move(dist), param_name,
                                            mode);
        return {esf, Update::sync};
    }
    else if (distribution == "uniform_real" or distribution == "uniform") {
        auto interval = get_as<std::array<double, 2>>("interval", cfg);
        std::uniform_real_distribution<> dist(interval[0], interval[1]);
 
        auto esf = build_rng_env_state_func(model, std::move(dist), param_name,
                                            mode);
        return {esf, Update::sync};
    }
    else {
        throw std::invalid_argument("No method implemented to resolve "
            "noise distribution '" + distribution + "'! Valid options: "
            "normal, poisson, uniform_int, uniform_real.");
    }
};

esf_slope()

template<typename EnvModel , typename Extent , class EnvStateFunc = typename EnvModel::EnvStateFunc>

std::pair< EnvStateFunc, Update > Utopia::Models::Environment::StateFunctionCollection::esf_slope	(	const EnvModel &	,
		const std::string &	param_name,
		const Config &	cfg,
		const Extent &	extent
	)

Creates a rule function for spatially linearly parameter values.

Parameters

param_name	The parameter to attach this environment function to
cfg	Configuration for this environment function. Allows the following arguments: mode: set (default) or add times: Sequence of time points values_north_south: Values at northern and souther boundary; uses linear interpolation in between.
extent	The extent of space

{
    const auto mode = extract_val_mode(cfg, "slope");
 
    const auto values_north_south =
        get_as<std::array<double, 2>>("values_north_south", cfg);
 
    EnvStateFunc esf =
        [param_name, mode, values_north_south, extent]
        (const auto& env_cell) mutable
    {
        auto& env_state = env_cell->state;
 
        // Use the relative position along y-dimension
        const double pos = (  env_state.position[1] / extent[1]);
        const double slope = values_north_south[0] - values_north_south[1];
        const double value = values_north_south[1] + pos * slope;
 
        double current_value = 0.;
        if (mode == ValMode::Add) {
            current_value = env_state.get_env(param_name);
        }
        env_state.set_env(param_name, current_value + value);
        return env_state;
    };
 
    return {esf, Update::sync};
};

esf_steps()

template<typename EnvModel , class EnvStateFunc = typename EnvModel::EnvStateFunc>

std::pair< EnvStateFunc, Update > Utopia::Models::Environment::StateFunctionCollection::esf_steps	(	const EnvModel &	,
		const std::string &	param_name,
		const Config &	cfg
	)

Creates a rule function for spatial steps in the parameter values.

Parameters

param_name	The parameter to attach this environment function to
cfg	Configuration for this environment function. Allows the following arguments: mode: set (default) or add times: Sequence of time points values_north_south: Sequence of parameter values for the step heights, from north to south. latitudes: Sequence of latitudes of separation, from north to south

{
    const auto mode = extract_val_mode(cfg, "steps");
 
    const auto latitudes =
        get_as<std::vector<double>>("latitudes", cfg, {0.5});
    const auto values_north_south =
        get_as<std::vector<double>>("values_north_south", cfg);
 
    if (latitudes.size() != values_north_south.size() - 1) {
        throw std::invalid_argument("The list of 'latitudes' and"
            " 'values_north_south' don't match in size. Sizes were "
            + std::to_string(latitudes.size()) + " and "
            + std::to_string(values_north_south.size()) +
            ". Values_north_south must have one element more that"
            " latitudes.");
    }
 
    EnvStateFunc esf =
        [param_name, mode, latitudes, values_north_south]
        (const auto& env_cell) mutable
    {
        auto& env_state = env_cell->state;
        double value = values_north_south[0];
        for (unsigned int i = 0; i < latitudes.size(); ++i) {
            if (env_state.position[1] > latitudes[i]) {
                break;
            }
            value = values_north_south[i+1];
        }
 
        double current_value = 0.;
        if (mode == ValMode::Add) {
            current_value = env_state.get_env(param_name);
        }
        env_state.set_env(param_name, current_value + value);
        return env_state;
    };
 
    return {esf, Update::sync};
};

esf_uniform()

template<typename EnvModel , class EnvStateFunc = typename EnvModel::EnvStateFunc>

std::pair< EnvStateFunc, Update > Utopia::Models::Environment::StateFunctionCollection::esf_uniform	(	const EnvModel &	,
		const std::string &	param_name,
		const Config &	cfg
	)

Creates a rule function for spatially uniform parameter values.

Parameters

param_name	The parameter to attach this environment function to
cfg	Configuration for this environment function. Allows the following arguments: mode: set (default) or add times: Sequence of time points value: The scalar value to use

{
    ValMode mode;
    double value;
 
    // Extract configuration depending on whether cfg is scalar or mapping
    if (cfg.IsScalar()) {
        // Interpret as desiring to set to the given scalar value
        mode = ValMode::Set;
        value = cfg.as<double>();
    }
    else if (cfg.IsMap()) {
        mode = extract_val_mode(cfg, "uniform");
        value = get_as<double>("value", cfg);
    }
    else {
        throw std::invalid_argument("The configuration for environment "
            "function 'uniform' must be a scalar or a mapping!");
    }
 
    EnvStateFunc esf =
        [param_name, mode, value]
        (const auto& env_cell) mutable
    {
        auto& env_state = env_cell->state;
 
        double current_value = 0.;
        if (mode == ValMode::Add) {
            current_value = env_state.get_env(param_name);
        }
 
        env_state.set_env(param_name, current_value + value);
        return env_state;
    };
 
    return {esf, Update::sync};
}

extract_time_start()

template<typename Time >

Time Utopia::Models::Environment::extract_time_start

(

const DataIO::Config &

cfg

)

Given a configuration, extracts the time of first function invocation.

                                                 {
    // get starting time
    auto times_list = get_as<std::vector<Time>>("times", cfg, {0});
    auto time_start = times_list.front();
    for (auto t : times_list) {
        if (t < time_start and t >= 0)
            time_start = t;
    }
 
    return time_start;
}

extract_times()

template<typename Time >

std::pair< bool, std::set< Time > > Utopia::Models::Environment::extract_times

(

const DataIO::Config &

cfg

)

Given a configuration, extracts the set of times at which to invoke environment functions

                                                                   {
    bool invoke_always = true;
    std::set<Time> times;
 
    if (not cfg.IsMap()) {
        // Already return here
        return {invoke_always, times};
    }
 
    // Extract information from configuration
    if (cfg["times"]) {
        invoke_always = false;
        auto times_list = get_as<std::vector<Time>>("times", cfg);
        // TODO Consider wrapping negative values around
 
        // Make sure negative times or 0 is not included
        // NOTE 0 may not be included because the environment state functions
        //      are invoked separately for this time.
        times_list.erase(
            std::remove_if(times_list.begin(), times_list.end(),
                           [](auto& t){ return (t <= 0); }),
            times_list.end()
        );
 
        // Populate the set; this will impose ordering
        times.insert(times_list.begin(), times_list.end());
    }
 
    return {invoke_always, times};
}

extract_times_and_initialization()

template<typename Time >

std::tuple< bool, bool, std::set< Time > > Utopia::Models::Environment::extract_times_and_initialization

(

const DataIO::Config &

cfg

)

Given a configuration, extracts the set of times at which to invoke environment functions and whether to invoke them at initialization

{
    bool invoke_at_initialization = get_as<bool>("invoke_at_initialization",
                                                 cfg);
 
    auto [invoke_always, times] = extract_times<Time>(cfg);
 
    return {invoke_at_initialization, invoke_always, times};
}

extract_val_mode()

ValMode Utopia::Models::Environment::extract_val_mode	(	const DataIO::Config &	cfg,
		const std::string &	context
	)

Given a configuration node, extract the value mode.

{
    const auto mode_key = get_as<std::string>("mode", cfg);
 
    if (mode_key == "add") {
        return ValMode::Add;
    }
    else if (mode_key == "set") {
        return ValMode::Set;
    }
 
    throw std::invalid_argument("The `mode` argument for configuration of "
        "environment function " + context + " can be 'add' or 'set', but "
        "was '" + mode_key + "'!");
}