:orphan: How to add a new script? ======================== So you want to extend the CEA? This guide will get you up and running! The main steps you need to take are: #. start with a script template. #. develop your script. #. add your script to the ``scripts.yml`` file #. add a section to the ``default.config`` file for any parameters your script requires Step 1: Start with a template ------------------------------ In ``cea/examples/template.py`` you will find a template for scripts in CEA. Go ahead and copy it to a location inside the ``cea`` folder hierarchy - check other scripts for a good place to locate it. If you need to create a subfolder, make sure you add an (empty) file called ``__init__.py`` to that folder - this makes the folder a python package and is essential for referencing the script later on. Rename the copied file to a name that describes your script as good as possible. You should now be able to run the script in PyCharm (or by hand with ``python -m cea.your_package_name.your_script_name``) and get the following output:: Running template with scenario = C:\reference-case-open\baseline Running template with archetypes = ['comfort', 'architecture', 'HVAC', 'internal-loads'] Inside the ``main`` function of your script, there is a section of ``print`` statements. It is a good idea to update this list to print out the parameters actually used by your script. The ``main`` function in the template calls a function ``template``, passing in an ``InputLocator`` object and unpacking the ``config`` parameter. We call this the "core" function of your script. You should definitely change the name of the core function - ideally to the name of the script / module it resides in. The ``InputLocator`` object (by convention called ``locator``) is used by nearly every single CEA script. The other parameters are much more dependent on the requirements of your script. If you find yourself adding more than a few parameters, consider just passing in the ``config`` variable instead, as long parameter lists in functions can make your code hard to read. While you're at it give it a Purpose and an Author!: - update the module-level documentation (at the top of the script) to reflect the _what_ and the _why_ of your script, including references to literature - update the documentation of the core function of your script (the one called ``template`` in the template) to reflect the __how__ of your script - update the credits section (near the top of the script) - be sure to change at least the following parts: - ``__author__`` (add your name!) - ``__credits__`` (add a list of names of colaborators) - ``__copyright__`` (update the year of the copyright for this script) Step 2: Develop your script ---------------------------- Each script is unique. But to fit nicely into the CEA ecosystem, pay attention to the following points: - spend some time to come up with good names for variables and functions - as a general rule, don't use abbreviations other than as loop indices (they're just hard to communicate later on) - beginners often think using short names and abbreviations is "cool" - this is probably the fault of decades and decades of bad examples in code. There used to be a time when it mattered, but nobody uses those languages anymore. It's a lot easier to read real words. - try to use the same names for the same thing - make sure the names refer to the subject domain of your script (this makes the leap between literature and your code easier to make for anyone trying to figure out what your script does later on) - use plural for names referring to lists, tuples, sets and dictionaries - check for spelling errors (this also counts for comments) - HINT: PyCharm has a built-in automatic spellchecker much like the one in MS Word. If PyCharm marks any of your code in yellow or green, try to figure out why and fix it! - don't hardcode paths! The CEA uses the ``cea.inputlocator.InputLocator`` class to define where files are. Follow this convention. - If you do need to manually create paths, use ``os.path.join(folder, ..., filename)`` instead of concatenating strings. - if you think you need to use ``os.chdir``, you're doing it wrong! Step 3: add your script to the ``scripts.yml`` file --------------------------------------------------- The ``scripts.yml`` file (located in ``cea/``) tells the ``cea`` command line program - the name of each script in the CEA - the module path of the script to run - the list of parameters that the script accepts - what interfaces (cli, dashboard) the script is meant to be used with - the category to list the script under By adding your script to the ``scripts.yml`` file, your script becomes executable from the command line like this:: $ cea your-script-name And you can use parameters like this: $ cea your-script-name --scenario C:\reference-case-open\baseline --your-parameter 123 During development of your script, you will probably not be too interested in this feature - you will probably just be running your script from PyCharm. Please take the time to do this anyway, since it is a *requirement for adding it to the dashboard interface*. The name of your script should be the same as the module name and the core function name from `Step 2: Develop your script`_ - except replace any underscores (``_``) with dashes (``-``). The ``scripts.yml`` file is grouped by categories and each category contains a list of scripts in that category. The syntax used is YAML_. The easiest way to add a new script is to copy an existing script definition. .. _YAML: https://en.wikipedia.org/wiki/YAML Here is an example category with a script:: Thermal networks: - name: thermal-network label: Thermo-hydraulic network (branched) description: Solve the thermal hydraulic network interfaces: [cli, dashboard] module: cea.technologies.thermal_network.thermal_network_matrix parameters: ['general:scenario', thermal-network] Note that whitespace is relevant in YAML - except for the newlines, I added them to make the structure easier to eyeball. The name of the category is "Thermal networks" and it consists of a list of cea scripts. Each script starts with a bullet point (a ``-``) and then a dictionary of script properties. These are the properties to define: name The script name. This is what is used to identify the script with the ``cea`` program and the other interfaces. It should use dashes (``-``) instead of underscores. Note the :py:mod:`cea.api` module provides a programmatic was of accessing these scripts as functions with the script names replacing the dashes with underscores (``_``). label A label to use in in the user interface description A description of the tool. This should be short but also contain a relevant description of the functionality. interfaces A list of interfaces the script is to be used with. (include "dashboard" for the script to show up in the GUI) module The fully qualified name (fqn) of the module that implements the script. This module is assumed to have a ``main`` function that takes one argument, a :py:class:`cea.config.Configuration` object. parameters A list of parameters that your script uses - use the notation ``section:parameter`` to specify a specific parameter defined in the ``default.config`` file. - use the notation ``section`` as a shorthand to specify that your script uses all the parameters from that section in the ``default.config`` file. Step 4: Add a section to the ``default.config`` file for any parameters your script requires -------------------------------------------------------------------------------------------- The file ``default.config`` (found in the ``cea`` folder) specifies the list of parameters the user can set for the CEA. This file has the same sections and parameters as the ``cea.config`` file in the user's home folder, except it also includes additional information like parameter type and a description of the parameter. The configuration is split up into sections. The main section ``[general]`` contains parameters that are considered global to most scripts, e.g. ``scenario``, ``weather``, ``multiprocessing``. All other parameters reside in a section with the same name as the script that uses them (e.g. ``[demand]``, ``[data-helper]`` etc.) with exceptions for tools that are closely related and share parameters (e.g. ``[solar]`` for ``photovoltaic``, ``solar-collector`` and ``photovoltaic-thermal``, ``[dbf-tools]`` for ``dbf-to-excel`` and ``excel-to-dbf``). Follow these steps to add a new parameter for your script: - add a section to ``default.config`` with the same name as the script or locate the appropriate section - add a parameter name: CEA parameter names follow the naming conventions of python variable names, except they use kebab-case_ instead of snake_case_, i.e. dashes instead of underscores. - set the default value - add a line specifying the type (key: ``parameter-name.type``, value: one of the ``Parameter`` subclasses from ``cea.config``, e.g. ``IntegerParameter``, ``RealParameter``, ``MultiChoiceParameter``, ``PathParameter`` etc.) - add a line specifying the documentation for the parameter (key: ``parameter-name.help``, value: the text to show in interfaces for that parameter - future users of your tool will be grateful for good help texts!) - (optional) add a line specifying the category of the tool (key: ``parameter-name.category``, value: the category name) The category is used in the interface to group advanced parameters for tools with a lot of parameters. Example:: [archetypes-mapper] input-databases = comfort, architecture, air-conditioning, internal-loads, supply, schedules input-databases.type = MultiChoiceParameter input-databases.choices = comfort, architecture, air-conditioning, internal-loads, supply, schedules input-databases.help = List of inputs to map from your databases to your new/existing scenario .. _kebab-case: http://wiki.c2.com/?KebabCase .. _snake_case: https://en.wikipedia.org/wiki/Snake_case