model.advanced_controls

An Advanced Controls object contains all the parameters for a given Scenario.

There is a 1:1 relationship between Advanced Controls objects and Scenario objects: each scenario has its Advanced Controls object in its ac field. You can think of a Scenario as: a Solution (the model and code) + the Advanced Controls (all the customized settings).

The Advanced Controls class has a field for every parameter that is used by any Solution, but not all Solutions use all parameters. (As a simple example, RSS type Solutions do not use parameters related to Land usage.) You can see which parameters a specific Solution uses by looking at the saved advanced controls objects in the 'ac' subdirectory of the solution definition.

Advanced Controls objects are frozen (immutable). To "change" a parameter value, you need to construct a new AdvancedControls/Scenario combination.

class SOLUTION_CATEGORY(enum.Enum):

An enumeration.

class AdvancedControls:

An immutable dictionary-like object of parameter values for a specific scenario.

AdvancedControls( solution_category: Any = None, vmas: Dict = None, vma_values: Dict = None, vma_statistics: Dict = None, name: str = None, description: str = None, creation_date: str = None, jsfile: str = None, pds_2014_cost: Any = None, ref_2014_cost: Any = None, conv_2014_cost: Any = None, soln_first_cost_efficiency_rate: float = None, conv_first_cost_efficiency_rate: float = None, soln_first_cost_below_conv: bool = None, soln_energy_efficiency_factor: float = 0.0, conv_annual_energy_used: float = 0.0, soln_annual_energy_used: float = 0.0, conv_fuel_consumed_per_funit: float = 0.0, soln_fuel_efficiency_factor: float = 0.0, conv_fuel_emissions_factor: float = 0.0, soln_fuel_emissions_factor: float = 0.0, conv_emissions_per_funit: float = 0.0, soln_emissions_per_funit: float = 0.0, ch4_is_co2eq: bool = None, n2o_is_co2eq: bool = None, co2eq_conversion_source: str = None, ch4_co2_per_funit: float = 0.0, n2o_co2_per_funit: float = 0.0, soln_indirect_co2_per_iunit: float = None, conv_indirect_co2_per_unit: float = None, conv_indirect_co2_is_iunits: bool = None, soln_lifetime_capacity: float = None, soln_avg_annual_use: float = None, conv_lifetime_capacity: float = None, conv_avg_annual_use: float = None, report_start_year: int = 2020, report_end_year: int = 2050, soln_var_oper_cost_per_funit: float = None, soln_fixed_oper_cost_per_iunit: Any = None, soln_fuel_cost_per_funit: float = None, conv_var_oper_cost_per_funit: float = None, conv_fixed_oper_cost_per_iunit: Any = None, conv_fuel_cost_per_funit: float = None, npv_discount_rate: float = None, emissions_use_co2eq: bool = None, emissions_grid_source: str = None, emissions_grid_range: str = None, soln_ref_adoption_regional_data: bool = None, soln_pds_adoption_regional_data: bool = None, soln_ref_adoption_basis: str = None, soln_ref_adoption_custom_name: str = None, soln_pds_adoption_basis: str = None, soln_pds_adoption_custom_name: str = None, soln_pds_adoption_scenarios_included: list[int] = None, soln_pds_adoption_custom_high_sd_mult: float = 1.0, soln_pds_adoption_custom_low_sd_mult: float = 1.0, soln_pds_adoption_prognostication_source: str = None, soln_pds_adoption_prognostication_trend: str = None, soln_pds_adoption_prognostication_growth: str = None, pds_source_post_2014: str = None, ref_source_post_2014: str = None, source_until_2014: str = None, ref_adoption_use_pds_years: List[int] = <factory>, pds_adoption_use_ref_years: List[int] = <factory>, ref_base_adoption: Dict = None, pds_adoption_final_percentage: Dict = None, pds_adoption_s_curve_innovation: Dict = None, pds_adoption_s_curve_imitation: Dict = None, tco2eq_reduced_per_land_unit: Any = None, tco2eq_rplu_rate: str = None, tco2_rplu_rate: str = None, tn2o_co2_rplu_rate: str = None, tch4_co2_rplu_rate: str = None, tco2_reduced_per_land_unit: Any = None, tn2o_co2_reduced_per_land_unit: Any = None, tch4_co2_reduced_per_land_unit: Any = None, emissions_use_agg_co2eq: bool = None, seq_rate_global: Any = None, seq_rate_per_regime: Dict = None, degradation_rate: Any = None, disturbance_rate: Any = None, global_multi_for_regrowth: float = None, soln_expected_lifetime: float = None, conv_expected_lifetime: float = None, yield_from_conv_practice: Any = None, yield_gain_from_conv_to_soln: Any = None, use_custom_tla: bool = None, custom_tla_fixed_value: float = None, harvest_frequency: float = None, carbon_not_emitted_after_harvesting: Any = None, avoided_deforest_with_intensification: Any = None, delay_protection_1yr: bool = None, delay_regrowth_1yr: bool = None, include_unprotected_land_in_regrowth_calcs: bool = None, land_annual_emissons_lifetime: bool = None, tC_storage_in_protected_land_type: Any = None, ref_tam_custom_source: str = None, pds_tam_custom_source: str = None, ref_adoption_custom_source: str = None, pds_adoption_custom_source: str = None)
def as_dict(self):

Return a dictionary data structure that is the serializable form of this object. This is used both for saving to files and for creating new instances.

def explain_parameter(self, parameter_name):

Return an explanation of a parameter, given its key

yield_coeff

Returns coeffecient that converts funits to yield for LAND solutions

has_var_costs

Returns Boolean to check if variable costs exist (LAND models don't have any). All variable costs must be not None for this to return True.

def lookup_vma(self, vma_title):

Look up a VMA value, using the value from the Advanced Controls, if any.

def with_modifications(self, **mods):

Return a new Advanced Controls object that is the same as this one, but with the requested fields modified. Note: the name is not changed unless it is specifically included in the modifications

def write_to_json_file(self, newname=None):
def fill_missing_regions_from_world(data):

AdvancedControls attributes linked to VMAs can optionally be Series of regional values rather than single floats. Some calculations in the model require all main regions (not special countries) to have values (i.e. not NaN); this function can be used to substitute any missing main regional values with the 'World' value, which is calculated as a weighted average of the available regional data by the VMA class. Note that in most cases it is better practice to input values for all main regions into the VMA table if regional data is to be considered for the solution.

Args
  • data: A Series object with REGIONS as index or float

Returns: the processed Series object or passes through float

def load_scenarios_from_json( directory, vmas, cls=<class 'model.advanced_controls.AdvancedControls'>):

Load scenarios from JSON files in directory.

def ac_from_dict( data: dict, vmas, filename='', cls=<class 'model.advanced_controls.AdvancedControls'>) -> model.advanced_controls.AdvancedControls:

Create an AdvancedControls object from a dictionary of values, as retrieved from a scenario json file.

def get_vma_for_param(param):
def get_param_for_vma_name(name, cls=<class 'model.advanced_controls.AdvancedControls'>):
def mangle_name_to_filename(name, suffix='json'):

Create a filename from a scenario (or any other) title

def solution_category_to_string(cat):
def string_to_solution_category(text):