Author and reviewer Checklist model documentation
Model documentation checklist
This page contains a description of all the information that should be present in the full model documentation pages. If a certain category is not applicable (when it is not modelled), please indicate this on the respective page.
Model Documentation (mandatory)
Introduction
- Mentions name and acronym of the model
- Describes the purpose of the model
- Explains the main features of the model
- Introduces the following sub-section
- Describes model concept and briefly describes how the model works
- Describes briefly any submodels/modules and their functions, and how they interact
- Describes which emissions are covered by the model
- Describes which regions are included in the model
- Describes time horizon of model and its timesteps
- Mentions the age of the model and summarizes main developments/history
- Mentions sources for other documentation
- If applicable, mentions availability open-source version
Model scope and methods (mandatory)
Introduction
- Provides a short summary of the model scope and methods sub-chapters
- Mentions purpose of the model
- Describes key characteristics of the model
- Describes the model concept and solver
- Describes briefly various key elements considered by the model
- Explains more elaborately how the model works and how submodels interact
- Describes the time horizon of the model
- Describes the context and organizational process in which the model is used
- Describes the inputs for the model
- Describes the outputs from the model
- Provide a visualization of the model framework, if available
- Mentions which emissions are covered by the model
- Describes where the model has been used
Model concept, solver and details (mandatory):
- Mentions purpose of the model
- Mentions model solution concept
- Mentions the solver(s) used
- Mentions modules / framework overview
- Mentions key elements/features considered/represented by the model
- Mentions harmonization year and calibration sources
- Provides a visualization of the model framework, if available
- Describes process steps for scenario simulation (calibration, defining a reference scenario, counterfactual simulations)
- Describes model history
- Describes where the model has been used
- Time steps, time horizon
- Explains how the model works
- Explains how is dealt with uncertainty, and provides an overview of key uncertainties
- Whether the model uses foresight
- Emissions accounted for
Temporal dimension (mandatory):
- Mentions base year/calibration year
- Mentions time horizon
- Mentions time step
- Whether the model has foresight
· Spatial dimension (mandatory) :
- Mentions whether the model is global
- Describes the regions included in the model
- Describes how regions interact with each other (e.g. trade (and traded goods), spillovers of products or technologies)
- Describes the spatial resolution of the model (e.g. when gridded data is used).
· Policy (mandatory):
- Describes in which areas policy can be introduced (e.g. mitigation, adaptation, energy, air pollution, land and agriculture, human development, etc)
- Describes which kind of policies can be introduced (carbon emission tax, renewable energy capacity targets, air pollution legislation, energy import taxes, efficiency standards, etc)
- Explains how policies are applied (e.g. by placing a price on emissions, fraction of power originating from a technology, apply subsidies, apply dietary preferences, etc)
- Mentions whether policy costs can be calculated and if so, summarizes what this entails
- Describes the purpose of policy modelling with the model
Socio-economic drivers (mandatory)
Introduction
- Describes what socio-economic drivers typically are
- Describes which socio-economic drivers are used by the model
- Briefly describes origin of socio-economic drivers
- Briefly describes purpose of socio-economic drivers for model
- Mentions whether socio-economic drivers are exogenous or (partly) endogenous.
Population (mandatory):
- Explains how the model is driven by population data
- Describes the population data typically used
- Mentions whether population is exogenous or (partly) endogenous.
Economic activity (mandatory):
- Explains how the model is driven by GDP data
- Describes the GDP data typically used
- Mentions whether GDP is exogenous or (partly) endogenous.
- If applicable, describes other economic activity variables that drive the model (e.g. Total Factor Productivity, production of steel)
Macro-economy
Introduction
- Provides a short summary of the macro-economy sub-chapters
- Explains if the macro-economy is endogenously modelled, or represented economic growth assumptions (the latter typically in simulation models).
- Describes any (sub-)models that represent the macro-economy.
- Provides the economic rationale behind the macro-economic representation
- Provides the main elements and inputs and outputs in the macro-economy calculations
- Describes the sectoral detail and sectoral differences
- Describes the regional detail and regional differences
- Describes the level of (intertemporal) optimization
Production system and representation of economic sectors
- Describes the production function, its main elements, inputs and outputs, and other key assumptions (e.g. substitution elasticity).
- Describes the represented economic sectors and sectoral assumptions.
· Capital and labour markets
- Describes the representation of capital and labour, any sectoral differences, other heterogeneity in the labour force, substitution assumptions, assumptions on wages, assumptions on capital mobility.
· Monetary instruments
· Describes any represented macro-economic policy instruments (fiscal policy, monetary policy and exchange rate policy) and the underlying assumptions.
· Trade
- Describes represented trade in the model. Including underlying economic principles, type of goods, calculation of prices, regional detail.
· Technological change:
- Explains if the model includes technological change and if so, how it is incorporated e.g.: learning-by-doing (exogenous, endogenous), R&D (exogenous, endogenous).
- Describes any representation of inertias and path-dependencies, e.g. via capacity stocks, knowledges stocks (cf. technological change), constraints of the expansion and decline of technology deployment, early retirements of fossil capacities.
Energy (mandatory)
Introduction
- Provides a short summary of the energy sub-chapters
- Mentions the name (and acronym) of the energy model.
- Provides the purpose/scope of the energy model in the broader context of the IAM.
- Describes briefly how the energy system is represented.
- Describe different levels (e.g. regions, sectors, energy carriers, etc.) that are represented.
- If applicable, links to detailed energy model documentation or source code.
- If relevant, includes references to other energy models that share similarities or have preceded the current model.
Energy resource endowments (mandatory):
Introduction
- Contains an overview of the energy carriers represented by the energy model
- Describes briefly the relevant modelled processes (e.g. production, trade, availability and depletion)
o Fossil energy resources (mandatory)
- Describes the represented energy carriers and resources/reserves.
- Describes how extractions costs and depletion are modelled.
- Mentions important assumptions or refers to data sources (e.g. costs, availability).
o Uranium and other fissile resources (mandatory)
- Describes how nuclear resources and fuel cycles are modelled.
- Mentions important assumptions or refers to data sources (e.g. costs, availability).
o Bioenergy
- Describes the represented feedstocks/resources (e.g. crop types, first/second generation).
- Describes how production costs are modelled.
- Describes how feedstock allocation and conversion are modelled.
- Mentions important assumptions or refers to data sources (e.g. costs, availability).
o Non-biomass renewables (mandatory)
- Describes which non-biomass renewables are covered (e.g. wind, solar PV, solar CSP, hydro, geothermal, tidal, etc.) by the model.
- Describes how the resource potentials and capacity factors are modelled.
- Describes how the costs (e.g. LCOE) are modelled.
- Mentions important assumptions or refers to data sources (e.g. costs, availability).
- Energy conversion* (mandatory)
- Describes how energy conversion is represented in the model.
- Indicates which conversion processes (from primary energy carriers to secondary energy carriers) are modelled.
- Indicates the relevant parameters that are considered by the model, such as costs, lifetimes, efficiencies, etc.
o Electricity (mandatory)
- Describes the represented electricity generation technologies.
- Describes which modelled energy sources are converted by which technology.
- Explains how the operational strategy of power generation is modelled and how intermittency and storage are dealt with.
- Mentions important assumptions about efficiencies, costs and lifetimes of technologies.
Heat
- Describes the represented heat generation technologies.
- Describes which modelled energy sources are converted by which technology.
- Mentions important assumptions about efficiencies, costs and lifetimes of technologies.
o Gaseous fuels
- Describes the represented technologies for hydrogen generation.
- Describes which modelled energy sources are converted by which technology.
- Mentions important assumptions about efficiencies, costs and lifetimes of technologies.
o Liquid fuels (mandatory)
- Describes the represented technologies for liquid fuel production.
- Describes which modelled energy sources are converted by which technology.
- Mentions important assumptions about efficiencies, costs and lifetimes of technologies.
o Solid fuels
- Describes the represented technologies for solid fuel production.
- Describes which modelled energy sources are converted by which technology.
- Mentions important assumptions about efficiencies, costs and lifetimes of technologies.
o Grid, pipelines and other infrastructure (mandatory)
(including systems integration of variable renewable energy sources)
- Describes the representation of energy infrastructure in the model, differentiated by sector and technology, if relevant.
- Describes represented energy storage technologies.
- Describes represented CCS technologies.
- Explains how the model factors in costs related to transmission, distribution, and infrastructure investments.
- Describes whether and how the pace of transitions in the model is influenced by infrastructure requirements.
- Energy end-use (mandatory)
- Describes the represented end-use sectors.
o Transport (mandatory)
Extent of the representation of different modes, technologies and costs of transport, modal shifts.
- Describes which transport sectors (travel, freight), modes and technologies are represented.
- Provides an overview of how transport is modelled (top-down or bottom-up).
- Describes which key concepts are used (e.g. travel-time budgets, activity-income-relation).
- Mentions the parameters that characterize vehicles and modal choices, including the most important drivers (e.g. efficiencies improvements, income growth).
- Mentions important assumptions or refers to data sources (e.g. costs, efficiency improvements).
o Residential and commercial sectors (mandatory)
How much detail is there for end use technologies? Are buildings represented within the model (e.g. different building ages and types? Are explicit efficiency options included (e.g. increased wall insulation, insulated glazing etc)?
- Describes which subsectors are modelled (residential, commercial) and which end-use services are represented (e.g. heating/cooling, cooking, appliances).
- Provides an overview of how the buildings sector is modelled (top-down or bottom-up).
- Mentions the parameters that determine service demand, including the most important drivers (e.g. floor area, heating degree days, income).
- Mentions important assumptions or refers to data sources (e.g. costs, efficiency improvements).
- Describes if and how heterogeneity is considered (e.g. different income groups, rural-urban).
o Industrial sector (mandatory)
How are the industrial sectors aggregated? How much detail is available for specific industrial processes and technologies?
- Provides an overview of the representation of the industrial sector, including relevant relationships.
- Mentions the most important subsectors that are modelled.
- Mentions the technologies that are represented (e.g. different technologies for production of cement, CCS, fuel substitution).
- Describes if and how the model incorporates material flows.
- Mentions important assumptions or refers to data sources (e.g. costs, efficiency improvements).
o Other end-use (mandatory)
Are there any other any industries explicitly modelled?
- Mentions which other sectors are explicitly represented.
- Describes how these other sectors are modelled.
- Mentions important assumptions or refers to data sources (e.g. costs, efficiency improvements).
- Energy demand (mandatory)
- Provides an overview of the energy demand modelling.
- Mentions which demand sectors (e.g. industry, transport) and physical quantities (e.g. energy, water, agricultural products) are represented.
- Describes whether demand sectors are endogenously represented in the model or exogenously defined.
- Describes how energy demand is linked to physical demand and/or activity levels (e.g. through econometric regression), including references to supporting literature.
- Includes references (if available) to demonstrate the responsiveness of energy demand in various SSP/policy scenarios.
- Technological change in energy (mandatory)
- Describes how technological change is modelled and how this depends on scenario assumptions (e.g. endogenously or exogenously represented).
- Mentions important assumptions or refers to data sources (e.g. costs, technology diffusion, learning curves).
Land-use
Introduction
- Provides a short summary of the land-use sub-chapters
- Mentions the name (and acronym) of the land-use model.
- Provides the purpose/scope of the land-use model in the broader context of the IAM.
- Describes briefly how land-cover and -use are represented.
- If applicable, links to detailed land-use model documentation or source code.
- If relevant, includes references to other land-use models that share similarities or have preceded the current model.
Agriculture
- Provides an overview of how agriculture is represented in the model.
- Describes components related to livestock production, potential crop yields and biomass production.
- Mentions important assumptions or refers to data sources (e.g. cropland and pasture areas, production costs, yield-fertilizer relationships).
- Forestry
- Provides an overview of how forestry is represented in the model.
- Describes how forest management, deforestation and forest degradation are modelled.
- Describes components related to timber production.
- Mentions important assumptions or refers to data sources (e.g. forest inventories, sustainability criteria, deforestation rates).
- Land-use change
- Describes how land-use change is modelled.
- Bioenergy land-use
How is the land use of bioenergy represented in the model?
- Describes how biofuel production is modelled.
- Other land-use: Any other land uses?
- Describes other land use sectors that are represented.
- Agricultural demand
- Describes the demand for goods and services produced on the land.
- Technological change in land-use
- Describes how technology affects yields.
- Describes how efficiency improvements are modelled.
- Mentions important assumptions or refers to data sources (e.g. costs, efficiency improvements).
Emissions (mandatory)
Introduction
- This section gives an introduction into the following subsections. Information from this section may be partly repeated in those subsections.
- Provides a general overview of the representation of emissions in the model, as well as lists the gases, aerosols or precursors that are represented. Common species are CO2, CH4, N2O, SO2, NOx, CO, NMVOC, F-gases (HFC’s, PFCs, SF6, NF3), BC, OC & NH3.
- Indicates for which sectors/sources the gases are modelled. It can be useful to create a table.
- Indicates if gases are modelled endogenously or exogenously.
- Provides a distinction between anthropogenic and natural sources.
- Explains the applied methods for calculating emissions (where relevant, mention activities, emission factors, abatement factors, and geographical specifications).
- Needs to contain references to relevant literature / data sources.
GHGs (mandatory)
Explains which greenhouse gases are included in the model and how are they linked to technologies and economy. This section can provide more detail than the introduction. E.g., provide assumed CO2 emission factors for different fuels, explain how CO2 emissions from biomass are treated, how non-CO2 emission reductions are modelled, etc.
- Needs to contain references to relevant literature / data sources.
· Pollutants and non-GHG forcing agents (mandatory)
Provides the non-greenhouse gas (i.e. pollutant) emissions that are included in the model (e.g. NOx, SOx, black and organic carbon, VOCs etc). Indicates if they are endogenous to the model (and if yes, how are they modelled) or projected exogenously, provides an overview of represented species by sector/source (or link to the introduction if it is mentioned there), explains how pollutant control can be enforced and how future air quality measures are modelled.
- Needs to contain references to relevant literature / data sources.
· Carbon dioxide removal (CDR) options (mandatory)
Indicates which CDR options are included in the model (such as bioenergy carbon capture and storage (BECCS) options, afforestation and reforestation, and direct air capture (DAC))
- Optional: Lists other fossil CCS options, but clearly distinguishes these non-CDR options from the aforementioned CDR options. If CCS options are provided under Energy Infrastructure, this page can also be linked.
- Needs to contain references to relevant literature / data sources.
Climate
- Provides the model’s main climate module or modelling routine and its main references. Generally, this is a reduced simplicity climate model (such as MAGICC) that emulates the behavior of complex climate models.
- Needs to contain references to relevant literature / data sources.
· Modelling of climate indicators.
- Indicates the main input and output variables of the climate model.
- Needs to contain references to relevant literature / data sources.
· Climate damages, temperature changes.
- Describes any monetary climate impacts that the model can calculate, as well as any adaptation to reduce monetary impacts. It should be clear if this is part of a default of optional run. These kind of calculations are typical of cost-benefit type IAMs (e.g. DICE, PAGE, FUND), but can sometimes also be coupled to process IAMs.
- Describes any biophysical impacts (and adaptation) represented in the model, both in default and optional runs. Economic impacts / Investments, heating / cooling demand, renewable and fossil energy supply potential, health, water use (in residential, power, industry and agriculture), agricultural land availability, sea level rise, flooding, extreme weather, biodiversity. When a category is included, it is relevant to describe how it is coupled to the rest of the model (i.e., fully coupled or output only).
- Needs to contain references to relevant literature / data sources.
Non-climate sustainability dimension
- This is a broad section that should contain an exhaustive overview of the non-climate sustainable categories representation. It is recommended to use the categorisation of the sustainable development goals. Where possible and relevant, the subchapters (air pollution and health, water, other materials and other sustainability dimensions) should be used for a more in-depth discussion of the SDG dimensions. The introduction can provide an overview of all represented SDG categories (e.g. with a table): No poverty (SDG 1), Zero hunger (SDG 2), Good health and well-being (SDG 3), Quality education (SDG 4), Gender equality (SDG 5), Clean water and sanitation (SDG 6), Affordable and clean energy (SDG 7), Decent work and economic growth (SDG 8), Industry, innovation and infrastructure (SDG 9), Reduced inequalities (SDG 10), Sustainable cities and communities (SDG 11), Responsible consumption and production (SDG 12), Climate action (SDG 13, note: excluded in this section), Life below water (SDG 14), Life on land (SDG 15), Peace, justice, and strong institutions (SDG 16), and Partnerships for the goals (SDG 17).
- A relevant addition to the introduction can be a description of the representation of LCA categories, e.g. when a model includes or can be linked to an LCA routine or model.
- If sustainability impacts are solely the result of climate change, these should be provided in the section ‘Climate damages, temperature changes’. Links between the sections can be added where relevant.
Air pollution and health
- Describes the representation of health impacts due to indoor and outdoor air pollution. It should be made clear if this is a default or optional calculation.
- Includes all pollutants that are included in health impact calculations.
- Includes all main relevant emissions to concentrations to heath impact calculations.
- Needs to contain references to relevant literature / data sources.
· Water
- Describes all main representations and model linkages concerning clean water and sanitation, including water consumption and withdrawal for the residential, industry, power and agricultural sectors.
- Needs to contain references to relevant literature / data sources.
· Other materials
- Describes all main representations and model linkages concerning material resource production and use in the model. That includes all metals, cement, minerals, plastics etc.
- Needs to contain references to relevant literature / data sources.
· Other sustainability dimensions
- Depending of if this is already described in the ‘non-climate sustainability dimension’ introduction, this section can contain a description of other relevant SDG dimensions: Poverty (SDG1), hunger (SDG2), energy access (SDG7), employment and economic growth (SDG8), innovation/R&D (SDG9), sustainable cities (SDG11), ecosystems/biodiversity (SDG14 and 15). Link to the non-climate sustainability dimension if the main information is described there.
- Needs to contain references to relevant literature / data sources.
Appendices
· Mathematical model description
- Optional but recommended if not included in other sections. This section can provide relevant mathematical model equations underlying the main processes in the model.
· Data
- Optional: This section can provide key data used in the model.
References (mandatory)
- Should include all key references including all references from the other sections.