New page and some minor fixes

gcam-xml.md

@@ -0,0 +1,91 @@
+# Understanding GCAM XML
+
+As described in the [overview](overview.hmtl), GCAM reads model structure and data from files written in [XML](https://en.wikipedia.org/wiki/XML), a hierarchical file format that is easy to parse and search. For working with XML files, it is convenient to use an XML editor that can expand and 
+collapse portions of the hierarchy.
+
+The XML inputs to GCAM v5.1.2 provides over 34 million lines of XML. The GCAM data system creates 217 files -- not all of which are used at the same time -- which must be assembled into a single hierarchy.
+
+## XML files are combined into a single XML tree
+
+GCAM's data files begin with:
+
+```XML
+<scenario>
+  <world>
+```
+
+and end with the corresponding closing tags:
+
+```XML
+  </world>
+</scenario>
+```
+The `scenario` node is the root of the hierarchy. As XML files are read in, in the order specified in the `configuration.xml` file, their contents are merged into this hierarchy. For example, if one file has this:
+
+```XML
+<scenario>
+  <world>
+    <region name="USA">
+      <x>1</x>
+      <y>42</y>
+    </region>
+  </world>
+</scenario>
+```
+
+And a second file has this:
+
+```XML
+<scenario>
+  <world>
+    <region name="Mexico">
+      <x>2</x>
+      <y>3</y>
+    </region>
+    <region name="USA">
+      <x>10</x>
+    </region>
+  </world>
+</scenario>
+```
+
+The merged result would be:
+
+```XML
+<scenario>
+  <world>
+    <region name="USA">
+      <x>10</x>
+      <y>42</y>
+    </region>
+    <region name="Mexico">
+      <x>2</x>
+      <y>3</y>
+    </region>
+  </world>
+</scenario>
+```
+
+The rules for combining XML data are these:
+
+1. If the element being read in includes the attribute `delete="1"`, any corresponding node in the document is deleted before the new node is added. That is, the `delete` attribute overrides the merging of content that would otherwise occur.
+
+2. If the element being read in includes the attribute `nocreate="1"`, the element will be merged into the document only if a corresponding node already exists in the document. Otherwise, the new element will be discarded.
+
+3. If the document has a container element with the same "path" (i.e., sequence of container elements from the root of the hierarchy) as the element being read in, the new element's contents are merged (recursively) with those already in the document. If no corresponding element previously existed in the document, the new element is added at the appropriate location.
+
+
+## Global Technology Database 
+
+To reduce redundancy, most technologies are defined in an element in the XML files called the `global-technology-database`, which we'll abbreviate here as GTDB. This provides common information about technologies, and of which can be overwritten in individual regions. Regional references to technologies in the GTDB are specified using the `stub-technology` element.
+
+The `global-technology-database` element occurs in 54 files in GCAM v5.1.2. As the XML files are read in, these elements are merged according to the rules above. After all of the XML files have been 
+read, all stub-technology nodes are replaced by copying the corresponding technology definition from the GTDB, and then merging any regionally-defined information for that technology, creating a region-specific version of the generic technology.
+
+## Pass-through sectors and technologies
+
+GCAM provides two levels of nesting: subsector and technology. Occasionally, additional levels of competition are needed to achieve the desired behavior. For example, (starting with GCAM v5) most electricity production technologies are further differentiated by cooling technology. To allow these additional levels of competition, GCAM allows “pass-through” sectors that provide additional levels of subsector/technology competition; the original “main” sector is represented with a technology that consumes the “pass-through” with a coefficient of 1 (perfect efficiency) and no additional costs. Pass through sectors must have only this one input.
+
+### Pass-through Example
+
+- An example and figure would be nice here

overview.md

@@ -18,7 +18,7 @@ GCAM is an integrated, multi-sector model that explores both human and Earth sys
 
 GCAM allows users to explore what-if scenarios, quantifying the implications of possible future conditions. These outputs are not predictions of the future; they are a way of analyzing the potential impacts of different assumptions about future conditions. GCAM reads in external "scenario assumptions" about key drivers (e.g., population, economic activity, technology, and policies) and then assesses the implications of these assumptions on key scientific or decision-relevant outcomes (e.g., commodity prices, energy use, land use, water use, emissions, and concentrations). 
 
-<img src="gcam-figs/overview_fig2.png" width="600"><br/>
+<img src="gcam-figs/overview_fig2.png" width="600" style="background-color:lightgray"><br/>
 Figure 1: Conceptual diagram of the way that IA models use scenario assumptions to produce fuller, modeled scenarios that include a wide range of additional information
 {: .fig}
 
@@ -28,7 +28,7 @@ Developing and quantifying a single set of scenario assumptions is the most comm
 
 The GCAM ecostystem includes a range of different tools, from data manipulation tools, the dynamic core of GCAM, and a range of disaggregation models, visualization tools and emulation tools. The GCAM release includes a data system for creatinig the XML inputs for GCAM and the dynamic core. Additional tools are produced and available separately and not included in the release version of GCAM.
 
-The [GCAM Data System](https://github.com/JGCRI/gcamdata) combines and reconciles a wide range of different data sets, and systematically incorporates a range of future assumptions. The output of the data system is an XML dataset with historical and base-year data for calibrating the model along with assumptions about future trajectories such as GDP, population, and technology. It includes the necessary information for representing energy, water, land, and the economic system. The GCAM Data System is largely constructed in R, but accommodates inputs in a range of different formats. Creating new scenarios does not require the use of the GCAM data system. New, "add on" xml files can be created to overwrite key future scenario assumptions such as population, economic activity, and technology cost and performance, among others.
+The [GCAM Data System](https://github.com/JGCRI/gcamdata) combines and reconciles a wide range of different data sets, and systematically incorporates a range of future assumptions. The output of the data system is an XML dataset with historical and base-year data for calibrating the model along with assumptions about future trajectories such as GDP, population, and technology. It includes the necessary information for representing energy, water, land, and the economic system. The GCAM Data System is largely constructed in R, but accommodates inputs in a range of different formats. Creating new scenarios does not require the use of the GCAM data system. New, "add on" xml files can be created to overwrite key future scenario assumptions such as population, economic activity, and technology cost and performance, among others. More information on GCAM XML files is available [here](gcam-xml.html).
 
 The GCAM core (discussed below) is the component of the model in which economic decisions are made (e.g., land use and technology choices), and in which dynamics and interactions are modeled within and among different human and Earth systems. The GCAM core is written in C++ and takes in inputs in XML. Outputs are written to a xml database.
 
@@ -88,7 +88,7 @@ The core operating principle for GCAM is that of market equilibrium. Representat
 
 As an example, in any single model period, GCAM derives a demand for natural gas starting with all of the uses to which natural gas might be put, such as passenger and freight transport, power generation, hydrogen production, heating, cooling and cooking, fertilizer production, and other industrial energy uses. Those demands depend on the external assumptions about, for example, electricity generating technology efficiencies, but also on the price of all of the commodities in the model. GCAM then calculates the amount of natural gas that suppliers would like to supply given their available technology for extracting resources and the market price. The model gathers this same information for all of the commodities and then adjusts prices so that in every market during that period supplies of everything from rice to solar power match demands.
 
-<img src="gcam-figs/overview_fig4.png" width="600"><br/>
+<img src="gcam-figs/overview_fig4.png" width="600" style="background-color:lightgray"><br/>
 Figure 3: Conceptual Schematic of the Operation of the GCAM Core
 {: .fig}
 

policies.md

@@ -33,9 +33,9 @@ Emissions prices of different GHGs can be linked together for a multi-gas policy
 The parameter price-adjust is used to convert prices (e.g., 100 year GWPs in the default set-up) and demand-adjust is used to convert demand units (e.g., to common units of carbon equivalents).
 These can be changed by year if desired.
 
-Setting price-adjust to zero means that there is no economic feedback for the price of this GHG. MAC curves, however, will still operate under the default set-up (whereby MAC curves are driven by CO<sub>2</sub> prices). This can be changed separately for energy/industrial/urban CH<sub>4</sub>, agricultural CH<sub>4</sub> (CH4\_AGR), and CH<sub>4</sub> from agricultural waste burning (CH4\_AWB), LUC CO<sub>2</sub> emissions (e.g. CO2_LUC).
+Setting price-adjust to zero means that there is no economic feedback for the price of this GHG. MAC curves, however, will still operate under the default set-up (whereby MAC curves are driven by CO<sub>2</sub> prices). This can be changed separately for energy/industrial/urban CH<sub>4</sub>, agricultural CH<sub>4</sub> (CH4\_AGR), and CH<sub>4</sub> from agricultural waste burning (CH4\_AWB), LUC CO<sub>2</sub> emissions (e.g. CO2_LUC).
 
-Note that you must first create a policy by reading in a <ghgpolicy> object (by reading an an XML with this object first, see the various policy files in the GCAM release) and then you can define how this links to any emissions (through <linked-ghg-policy> objects).
+Note that you must first create a policy by reading in a `<ghgpolicy>` object (by reading an an XML with this object first, see the various policy files in the GCAM release) and then you can define how this links to any emissions (through `<linked-ghg-policy>` objects).
 
 This flexibility allows CO<sub>2</sub>-only, CO<sub>2</sub>-equivalent, or non-CO<sub>2</sub> markets/constraints for various “baskets” of emissions as needed.