====================================
PowerFD Component Specification
====================================

.. contents:: Contents
    :local:

Overview
========
**PowerFD component** is a feature descriptor.
This component exponentiates input.
The scale of the input must be INTEGER or REAL.
This component calculates not only the power, but also the power's reciprocal.

**Example**: Squaring input

* SPD:

 .. code-block:: python

   dl1 -> power1

   ---

   components:
       dl1:
           component: DataLoader

       power1:
           component: PowerFDComponent
           features: scale == 'real' or scale == 'integer'
           power: 2

* Input of the component:

 +--------+---------------+------------+
 |   _sid |   temperature |   pressure |
 +========+===============+============+
 | 0      | 22.3          | 1001       |
 +--------+---------------+------------+
 | 1      | 21.8          | 1002       |
 +--------+---------------+------------+
 | 2      | inf           | NaN        |
 +--------+---------------+------------+
 | 3      | 23.4          | 1002       |
 +--------+---------------+------------+
 | 4      | -inf          | 1002       |
 +--------+---------------+------------+

* Output of the component:

 +--------+----------------------+-------------------+
 |   _sid |   power1_temperature |   power1_pressure |
 +========+======================+===================+
 |   0    | 497.290000           | 1002001           |
 +--------+----------------------+-------------------+
 |   1    | 475.240000           | 1004004           |
 +--------+----------------------+-------------------+
 |   2    |        inf           |     NaN           |
 +--------+----------------------+-------------------+
 |   3    | 547.560000           | 1004004           |
 +--------+----------------------+-------------------+
 |   4    |        inf           | 1004004           |
 +--------+----------------------+-------------------+

|

**Example**: Getting the reciprocal of input

* SPD:

 .. code-block:: python

   dl1 -> power1

   ---

   components:
       dl1:
           component: DataLoader

       power1:
           component: PowerFDComponent
           features: scale == 'real' or scale == 'integer'
           power: -1

* Input of the component:

 +--------+---------------+------------+
 |   _sid |   temperature |   pressure |
 +========+===============+============+
 | 0      | 22.3          | 1001       |
 +--------+---------------+------------+
 | 1      | 21.8          | 1002       |
 +--------+---------------+------------+
 | 2      | inf           | NaN        |
 +--------+---------------+------------+
 | 3      | 23.4          | 1002       |
 +--------+---------------+------------+
 | 4      | -inf          | 1002       |
 +--------+---------------+------------+

* Output of the component:

 +--------+----------------------+-------------------+
 |   _sid |   power1_temperature |   power1_pressure |
 +========+======================+===================+
 |   0    | 0.044843             | 0.000999          |
 +--------+----------------------+-------------------+
 |   1    | 0.045872             | 0.000998          |
 +--------+----------------------+-------------------+
 |   2    | 0.000000             |     NaN           |
 +--------+----------------------+-------------------+
 |   3    | 0.042735             | 0.000998          |
 +--------+----------------------+-------------------+
 |   4    | -0.000000            | 0.000998          |
 +--------+----------------------+-------------------+

This component has no component-specific external formats.

.. seealso::

    Component-common external format files in :ref:`convert_process`

|

Parameters
==========
Here is the component-specific parameter for the **PowerFD component**.

SPD
---

The following parameter is for "components" section of SPD.

.. list-table::
  :header-rows: 1
  :widths: 10, 5, 15, 10, 50

  * - Parameter Name
    - Type
    - Domain
    - Default Value
    - Description
  * - power [1]_
    - float
    - (-inf,0), (0,inf)
    - --
    - The power index.

.. [1] Required parameter

|

Utilizable Sample Metadata
==========================
There are no component-specific sample metadata available.

|

Output Attributes
=================
**PowerFD component** generates the following attribute:

.. list-table::
  :header-rows: 1
  :widths: 3,1,3

  * - Attribute Name
    - Scale
    - Description
  * - *<component_id>*\ _\ *<original_attribute_name>*
    - REAL
    - Raised value of the original attribute.

These attributes are in the component output data. These can be loaded
in SAMPO API or saved as data.csv after executing :ref:`convert_process`.

.. seealso::

    Obtaining process results via `ProcessResultLoader <../../api/process_result_loader.html>`_.

|

Attribute Metadata
==================
The metadata of the output attributes is created with the following rules.

Context Rule
------------
.. list-table::
  :header-rows: 1
  :widths: 3,1,3

  * - Attribute Name 
    - Context Name
    - Description
  * - *<component_id>*\ _\ *<original_attribute_name>*
    - power
    - Set the value of ``power``.

Derivation Rule
---------------
Each new attribute is derived from the corresponding attribute selected by the ``features`` parameter of the component.

Example
-------
.. code-block:: javascript

    {
        "nodes": [
            {"aid": "_sid", "name": "_sid", ... },
            {"aid": "dl1[0]", "name": "temperature", ... },
            {"aid": "dl1[1]", "name": "pressure", ... },
            {"aid": "power1[0]", "name": "power1_temperature", "scale": "real",
             "is_excluded": false, "cid": "power1", "cindex": 0, "values": null, 
             "is_kept": false, "context": {"power": 2}}, 
            {"aid": "power1[1]", "name": "power1_pressure", "scale": "real",
             "is_excluded": false, "cid": "power1", "cindex": 1, "values": null, 
             "is_kept": false, "context": {"power": 2}}
        ], 
        "links": [
            {"source": "dl1[0]", "target": "power1[0]"}, 
            {"source": "dl1[1]", "target": "power1[1]"}
        ]
    }

.. seealso::
    
    Attribute metadata file format in :ref:`Attribute Metadata File Specification <attribute-metadata>`

|

Details
=======
* In the learning phase, this component only checks the validity of the parameters by checking whether the condition below is satisfied:

  * The attribute scale must be INTEGER or REAL.

* In the running phase, this component exponentiates an input.

  * When two results are possible (positive value/negative value), only the positive one is returned. For example, although the square root of :math:`4` is :math:`-2` and :math:`2`, this component returns only :math:`2`.
