Configuration modules
=====================

CustomConfig Module
-------------------

This module provides functions for managing the configuration of the T-reX package.
This is only needed if you have installed the package from PyPi, if you have cloned the repository you can just edit the configuration files directly.

By running the following command, the program will create a folder ``config`` in the current working directory containing the default configuration files:

.. code-block:: python

    T-reX.config.config_setup()

You can then edit these files to match your project structure and your needs. And then run the following command to reload the configuration:

.. code-block:: python

    T-reX.config.config_reload()

You will then need to restart your python session for the changes to take effect.
If you want to reset the configuration to the default values, you can run:

.. code-block:: python

    T-reX.config.config_reset()


General Settings: ``user_settings.py``
---------------------------------------

This is the main configuration file, the one that you might want to edit to match your project structure and your needs. By default, the program will take a brightway2 project named ``default`` and copy that to a new project named ``SSP-cutoff``, which is then copied to a new project named ``T_reXootprint-SSP-cutoff``.

Doing it this way isolates the components and allows you to keep your original brightway2 project as it was. If space is an issue, you can set all of the project names to be the same.

If you are happy with the default settings, you can just run the program and it will create the databases for you. If you want to change the settings, you can edit the ``user_settings.py`` file that you can find in the ``config`` directory of your working directory.

These are some extracts from ``user_settings.py`` with the most important settings (the ones you might want to change) and their default values:

.. code-block:: python

    # Choose whether to use premise to create future scenario databases 
    use_premise = True
    # Choose whether to use T-reX to edit the databases (you could also turn this off and just use the package as an easy way to make a set of future scenario databases)
    use_T_reX = True

    # Choose the names of the projects to use
    project_premise_base = "default"
    project_premise = "SSP-cutoff"
    project_base = project_premise
    project_T_reX = f"T_reXootprint-{project_base}"

    # Choose the name of the database to use (needed for premise only, the T-reX tool will run all databases except the biospheres)
    database_name = "ecoinvent-3.9.1-cutoff"

    # if you want to use a fresh project
    delete_existing_premise_project = False
    delete_existing_T_reX_project = False

    # Choose the premise scenarios to generate (see FutureScenarios.py for more details)
    # Not all combinations are available, the code in FutureScenarios.py will filter out the scenarios that are not possible
    # the default is to have an optimistic and a pessimistic scenario with SSP2 for 2030, 2065 and 2100

    models = ["remind"]
    ssps = ["SSP2"]
    rcps = ["Base","PkBudg500"]
    years = [2030,2065,2100,]

Waste Search Settings: ``queries_waste.py``
-------------------------------------------

This file sets up search parameters for different T-reX flow categories, crucial for the ``SearchWaste.py`` script. It leverages a ``.pickle`` file created by ``ExplodeDatabase.py``.

Categories
^^^^^^^^^^

Handles various categories like digestion, composting, incineration, recycling, landfill, etc.

Query Types
^^^^^^^^^^^

Two sets of queries are created:

1. ``queries_kg`` for waste flows in kilograms.
2. ``queries_m3`` for waste flows in cubic meters.

Adjusting Search Terms
^^^^^^^^^^^^^^^^^^^^^^

- **Search Keywords**: Tweak the ``AND``, ``OR``, ``NOT`` lists to refine your search.

Category-Specific Changes
^^^^^^^^^^^^^^^^^^^^^^^^^

- **Adding Categories**: You can add new categories to the ``names`` list.
- **Modifying Queries**: Update the query parameters for each category based on your requirements.

Optimising Search Efficiency
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can choose to include or exclude whatever you want. For instance, "non-hazardous" is not included as it's derivable from other categories and slows down the process.

Validating Search Terms
^^^^^^^^^^^^^^^^^^^^^^^

Isolate the function of ``SearchWaste.py`` to validate your search terms. That means, turning off the other functions in ``user_settings.py``, or running the module directly. You can achieve this by setting the following in ``user_settings.py``:

.. code-block:: python

    use_premise = False
    do_search = True
    do_methods = False
    do_edit = False

Material Search Settings: ``queries_materials.py``
--------------------------------------------------

The ``queries_materials`` module creates demand methods in the T-reX tool. It aligns with the EU CRM list 2023 and the ecoinvent database, incorporating additional strategic materials for comprehensive analysis. More can be easily added, as wished by the user.

This function uses the string tests ``startswith`` in ``SearchMaterial.py`` to identify activities beginning with the specified material name. This allows one to be more specific with the search terms (the ``,`` can be critical sometimes).

Structure and Customisation
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Tuple Structure
"""""""""""""""

- **First Part (Activity Name)**: Specifies the exact activity in the database (e.g., ``market for chromium``).
- **Second Part (Material Category)**: Aggregates related activities under a common category (e.g., ``chromium``), enhancing data processing efficiency.

Customisation Options
"""""""""""""""""""""

- **Add or Remove Materials**: Adapt the tuple list by including new materials or removing irrelevant ones.
- **Refine Search Terms**: Update material categories for a better fit with your database, ensuring precision in naming, especially with the use of commas.

Usage Considerations
^^^^^^^^^^^^^^^^^^^^

- **Material Quantity**: The current list comprises over 40 materials. Modify this count to suit your project's scope.
- **Database Alignment**: Check that the material names correspond with your specific database version, like ecoinvent v3.9.1.

Example Tuples
""""""""""""""

- ``("market for chromium", "chromium")``
- ``("market for coal", "coal")``
- ``("market for cobalt", "cobalt")``
- ``("market for coke", "coke")``
- ``("market for copper", "copper")``
- ``("market for tap water", "water")``
- ``("market for water,", "water")``