resPolicy.xml
===================
The ``resPolicy.xml`` file defines a renewable energy standard policy for
the electricity sector. (Support for other sectors is coming.)

XML elements
------------

The elements that comprise the ``resPolicy.xml`` file are described below.


<portfolio-standards>
^^^^^^^^^^^^^^^^^^^^^^^^^^
This is the outermost element, which takes no attributes and contains one
or more ``<portfolio-standard>`` elements. It may also contain ``<comment>``
elements.

<portfolio-standard>
^^^^^^^^^^^^^^^^^^^^^^^^^^
Defines a single portfolio standard, for a given set of regions.
This element takes no attributes and contains one or more
``<certificate>`` elements, and zero or more ``<comment>`` elements.

<certificate>
^^^^^^^^^^^^^
The ``<certificate>`` element defines a single renewable energy certificate,
or REC, that is generated by electricity producers that are incentivized by
the policy, and consumed by technologies deemed regulated by the policy.

The ``<certificate>`` element takes a single required attribute, ``name``,
which is the name of the traded REC.

+-------------+------------+-----------+----------+
| Attribute   | Required   | Default   | Values   |
+=============+============+===========+==========+
| name        | yes        | (none)    | text     |
+-------------+------------+-----------+----------+

A ``<certificate>`` element must include exactly one of each of the following
sub-elements: ``<targets>``, ``<producers>``, and ``<consumers>``, and may
contain any number of ``<comment>`` elements.

<targets>
^^^^^^^^^^^^^

The ``<targets>`` element takes no attributes and must contain one or more
``<target>`` elements, and any number of ``<comment>`` elements.

<target>
^^^^^^^^^^^^^
The ``<target>`` element defines the required fraction of total output that
must be covered by RECs, by year. That is, for a 20% RPS in 2020, each regulated
electricity provider would have a target of ``<target year="2020" fraction="0.2"/>``.

+-------------+------------+-----------+----------+
| Attribute   | Required   | Default   | Values   |
+=============+============+===========+==========+
| year        | yes        | (none)    | text     |
+-------------+------------+-----------+----------+
| fraction    | yes        | (none)    | float    |
+-------------+------------+-----------+----------+

<producers> and <consumers>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``<producers>`` defines technologies deemed to produce RECs, i.e., the
renewable technologies incentivized by the policy. The ``<consumers>`` element
defines those technologies which must acquire credits at the level described
in the ``<targets>``.

The ``<producers>`` and ``<consumers>`` take no attributes, and must each
contain one or more ``<tech>`` elements, can have and any number of ``<comment>``
elements.

<tech>
^^^^^^^
The ``<tech>`` element identifies a single technology or set of technologies.
It takes 3 attributes: The (required) ``sector`` attribute identifies a
sector containing some number of technologies. This can be an exact match
for a technology (in the global-technology-database) or a regular expression
matching multiple sectors. The other two attributes, ``subsector`` and
``technology`` are optional; if not specified all technologies matching the
sector and subsector (if ``subsector`` is provided) or sector (if ``subsector``
is absent) are matched. As with ``sector``, ``subsector`` and ``technology``
can be exact matches or regular expressions.

+-------------+------------+-----------+----------+
| Attribute   | Required   | Default   | Values   |
+=============+============+===========+==========+
| sector      | yes        | (none)    | text     |
+-------------+------------+-----------+----------+
| subsector   | no         | (none)    | text     |
+-------------+------------+-----------+----------+
| technology  | no         | (none)    | text     |
+-------------+------------+-----------+----------+


Example
^^^^^^^^

  .. code-block:: xml

     <portfolio-standards xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="RES-schema.xsd">

        <portfolio-standard market="Brazil" regions="Brazil">

            <certificate name="Brazil-REC">
                <targets>
                    <target years="2020" fraction="0.15"/>
                    <target years="2025" fraction="0.175"/>
                    <target years="2030" fraction="0.20"/>
                    <target years="2035" fraction="0.225"/>
                    <target years="2040" fraction="0.25"/>
                    <target years="2045" fraction="0.275"/>
                    <target years="2050" fraction="0.30"/>
                </targets>
                <producers>
                    <!-- incentivized sectors and technologies produce certificates -->
                    <tech sector="elect_td_bld" subsector="rooftop_pv"/>
                    <tech sector="electricity" subsector="^solar|wind|hydro$"/>
                    <tech sector="^elec_(?:biomass|geothermal).*"/>
                </producers>
                <consumers>
                    <!-- regulated sectors and technologies consume certificates -->
                    <tech sector="elect_td_bld" subsector="rooftop_pv"/>
                    <tech sector="electricity" subsector="^solar|wind|hydro$"/>
                    <tech sector="^elec_.*"/>
                </consumers>
            </certificate>
        </portfolio-standard>

        <portfolio-standard market="China" regions="China">
            <certificate name="China-REC">
                <targets>
                    <target years="2020" fraction="0.20"/>
                    <target years="2025" fraction="0.25"/>
                    <target years="2030" fraction="0.30"/>
                    <target years="2035" fraction="0.35"/>
                    <target years="2040" fraction="0.40"/>
                    <target years="2045" fraction="0.45"/>
                    <target years="2050" fraction="0.50"/>
                </targets>
                <producers>
                    <!-- incentivized sectors and technologies produce certificates -->
                    <tech sector="electricity" subsector="^solar|wind|hydro$"/>
                    <tech sector="^elec_(?:biomass|geothermal).*"/>
                    <tech sector="elec_CSP"/>
                </producers>
                <consumers>
                    <!-- regulated sectors and technologies consume certificates -->
                    <tech sector="electricity" subsector="^solar|wind|hydro$"/>
                    <tech sector="^elec_.*"/>
                </consumers>
            </certificate>
        </portfolio-standard>
     </portfolio-standards>