.. _outputRequest:

Output requests
===============

In the context of a simulation, the ``outputRequest`` category contains
all output requests, that is to say all results the user would like to
get after the simulation run.


The simulation category follows the same rules as the ``link`` category. 
The main schema is :

::

    data.h5
    `-- outputRequest/
        `-- $outputRequest_group/
            `-- $outputRequest_instance


The output request instance
---------------------------

Subject and object
^^^^^^^^^^^^^^^^^^

An output request instance is the association between a label and an element. 
The output request labels are picked in a label dataset in the ``/label``
category :

::

    data.h5
    |-- label/
    |   `-- $outputRequest
    `-- outputRequest/
        `-- $outputRequest_group/
            `-- $outputRequest_instance


where ``data.h5:/label/$outputRequest`` (the name is not specified
by |namespec|) is :

+----------------------------------+
| E field computation              |
+----------------------------------+
| H field computation              |
+----------------------------------+

Then a link instance is built between a label and a mesh entity (or whatever
element in the |namespec| instance :

::

    data.h5
    |-- label/
    |   `-- $outpuRequest
    |-- mesh/
    |   `-- $gmesh1
    |       `-- $plane
    |           `-- group
    |               `-- $wing
    `-- outputRequest/
        `-- $outputRequest_group/
            `-- $outputRequest_instance[@subject=/label/$outputRequest
                                        @subject_id=1
                                        @object=/mesh/$gmesh1/$plane/group/$wing]


The ``output`` attribute
^^^^^^^^^^^^^^^^^^^^^^^^

Output results (numerical or not) are |namespec| objects with an absolute name
like all objects. The ``output`` attribute of
``data.h5:/outputRequest/$outputRequest`` is an HDF5 string attribute which
contains the name of the object result. For instance :

::

    data.h5
    |-- label/
    |   `-- $outpuRequest
    |-- mesh/
    |   `-- $gmesh1
    |       `-- $plane
    |           `-- group
    |               `-- $wing
    |-- floatingType/
    |   |-- $e_field
    |   `-- $h_field
    `-- outputRequest/
        `-- $outputRequest_group/
            |-- $outputRequest_instance1[@subject=/label/$outputRequest
            |                            @subject_id=0
            |                            @object=/mesh/$gmesh1/$plane/group/$wing
            |                            @output=/floatingType/$e_field]
            `-- $outputRequest_instance2[@subject=/label/$outputRequest
                                         @subject_id=1
                                         @object=/mesh/$gmesh1/$plane/group/$wing
                                         @output=/floatingType/$h_field]

In this example, the computed electric field will be store in
``data.h5:/floatingType/$e_field`` and the magnetic field in
``data.h5:/floatingType/$h_field``

.. note::
    In the simulation input file, ``data.h5:/floatingType/$e_field`` is empty.
    In the simulation output file, ``data.h5:/floatingType/$e_field`` contains
    the result data.


The predefined output requests
------------------------------

Amelet-HDF predefines some output resquests, they are detailed in 
the next sections.


The predefined outputRequest dataset
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The predefined output request label list is :

::

    data.h5
    `-- label/
        `-- predefinedOutputRequests



This dataset contains the following labels :

+---+----------------------------------+
| 0 | electricField                    |
+---+----------------------------------+
| 1 | magneticField                    |
+---+----------------------------------+
| 2 | powerDensity                     |
+---+----------------------------------+
| 3 | planeWaveDecomposition           |
+---+----------------------------------+
| 4 | current                          |
+---+----------------------------------+
| 5 | voltage                          |
+---+----------------------------------+
| 6 | power                            |
+---+----------------------------------+
| 7 | sParameter                       |
+---+----------------------------------+
| 8 | zParameter                       |
+---+----------------------------------+
| 9 | yParameter                       |
+---+----------------------------------+
|10 | theveninVoltageGenerator         |
+---+----------------------------------+
|11 | nortonCurrentGenerator           |
+---+----------------------------------+
|12 | couplingCrossSection             |
+---+----------------------------------+
|13 | radarCrossSection                |
+---+----------------------------------+

(The first column of the array is informative)


Electromagnetic field computation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This section contains output request examples concerning 
electromagnetic field computation.



Electric field computation in a volume
######################################

The electric field computation request in a volume can be written as :

::

    data.h5
    |-- label/
    |   `-- predefinedOutputRequests
    |-- mesh/
    |   `-- $gmesh1
    |       `-- $sphere
    |           `-- group
    |               |-- $inside[@type=volume]
    |               `-- $skin[@type=face]
    |-- floatingType/
    |   `-- $e_field
    `-- outputRequest/
        `-- $outputRequest_group/
            `-- $or1[@subject=/label/predefinedOutputRequests
                     @subject_id=0
                     @object=/mesh/$gmesh1/$sphere/group/$inside
                     @output=/floatingType/$e_field]



H field computation in a volume
###############################

The magnetic field computation request in a volume can be written as :

::

    data.h5
    |-- label/
    |   `-- predefinedOutputRequests
    |-- mesh/
    |   `-- $gmesh1
    |       `-- $sphere
    |           `-- group
    |               |-- $inside[@type=volume]
    |               `-- $skin[@type=face]
    |-- floatingType/
    |   `-- $h_field
    `-- outputRequest/
        `-- $outputRequest_group/
            `-- $or1[@subject=/label/predefinedOutputRequests
                     @subject_id=1
                     @object=/mesh/$gmesh1/$sphere/group/$inside
                     @output=/floatingType/$h_field]


E field computation on surface
##############################

The electric field computation request on a surface can be written as :

::

    data.h5
    |-- label/
    |   `-- predefinedOutputRequests
    |-- mesh/
    |   `-- $gmesh1
    |       `-- $sphere
    |           `-- group
    |               |-- $diameter[@type=edge]
    |               |-- $inside[@type=volume]
    |               `-- $skin[@type=face]
    |-- floatingType/
    |   `-- $e_field
    `-- outputRequest/
        `-- $outputRequest_group/
            `-- $or1[@subject=/label/predefinedOutputRequests
                     @subject_id=0
                     @object=/mesh/$gmesh1/$sphere/group/$skin
                     @output=/floatingType/$e_field]


H field computation on surface
##############################

The magnetic field computation request on a surface can be written as :

::

    data.h5
    |-- label/
    |   `-- predefinedOutputRequests
    |-- mesh/
    |   `-- $gmesh1
    |       `-- $sphere
    |           `-- group
    |               |-- $diameter[@type=edge]
    |               |-- $inside[@type=volume]
    |               `-- $skin[@type=face]
    |-- floatingType/
    |   `-- $h_field
    `-- outputRequest/
        `-- $outputRequest_group/
            `-- $or1[@subject=/label/predefinedOutputRequests
                     @subject_id=1
                     @object=/mesh/$gmesh1/$sphere/group/$skin
                     @output=/floatingType/$h_field]


E field computation on line
###########################

The electric field computation request on a surface can be written as :

::

    data.h5
    |-- label/
    |   `-- predefinedOutputRequests
    |-- mesh/
    |   `-- $gmesh1
    |       `-- $sphere
    |           `-- group
    |               |-- $diameter[@type=edge]
    |               |-- $inside[@type=volume]
    |               `-- $skin[@type=face]
    |-- floatingType/
    |   `-- $e_field
    `-- outputRequest/
        `-- $outputRequest_group/
            `-- $or1[@subject=/label/predefinedOutputRequests
                     @subject_id=0
                     @object=/mesh/$gmesh1/$sphere/group/$diameter
                     @output=/floatingType/$e_field]


H field computation on line
###########################

The magnetic field computation request on a line can be written as :

::

    data.h5
    |-- label/
    |   `-- predefinedOutputRequests
    |-- mesh/
    |   `-- $gmesh1
    |       `-- $sphere
    |           `-- group
    |               |-- $diameter[@type=edge]
    |               |-- $inside[@type=volume]
    |               `-- $skin[@type=face]
    |-- floatingType/
    |   `-- $h_field
    `-- outputRequest/
        `-- $outputRequest_group/
            `-- $or1[@subject=/label/predefinedOutputRequests
                     @subject_id=0
                     @object=/mesh/$gmesh1/$sphere/group/$diameter
                     @output=/floatingType/$h_field]


Power density computation
#########################

The power computation request can be written as :

::

    data.h5
    |-- label/
    |   `-- predefinedOutputRequests
    |-- mesh/
    |   `-- $gmesh1
    |       `-- $sphere
    |           `-- group
    |               |-- $diameter[@type=edge]
    |               |-- $inside[@type=volume]
    |               `-- $skin[@type=face]
    |-- floatingType/
    |   `-- $power_density
    `-- outputRequest/
        `-- $outputRequest_group/
            `-- $or1[@subject=/label/predefinedOutputRequests
                     @subject_id=2
                     @object=/mesh/$gmesh1/$sphere/group/$volume
                     @output=/floatingType/$power_density]


Plane wave decomposition
^^^^^^^^^^^^^^^^^^^^^^^^

The plane wave decomposition request can be written as :

::

    data.h5
    |-- label/
    |   `-- predefinedOutputRequests
    |-- mesh/
    |   `-- $gmesh1
    |       `-- $sphere
    |           `-- group
    |               |-- $diameter[@type=edge]
    |               |-- $inside[@type=volume]
    |               `-- $skin[@type=face]
    |-- floatingType/
    |   |-- $magnitude
    |   |-- $polarization
    |   `-- $propagation_vector
    |-- group/
    |   `-- $wave_decomposition
    `-- outputRequest/
        `-- $outputRequest_group/
            `-- $or1[@subject=/label/predefinedOutputRequests
                     @subject_id=3
                     @object=""
                     @output=/group/$wave_decomposition]

and after the run ``data.h5:/group/$wave_decomposition`` will be :

+-----------------------------------+
| /floatingType/$magnitude          |
+-----------------------------------+
| /floatingType/$polarization       |
+-----------------------------------+
| /floatingType/$propagation_vector |
+-----------------------------------+



Cable
^^^^^

This section presents the output request on wire and cable structures.

Wire current
############

::

    data.h5
    |-- label/
    |   `-- predefinedOutputRequests
    |-- mesh/
    |   `-- $gmesh1
    |       `-- $sphere
    |           |-- nodes
    |           |-- elementTypes
    |           |-- elementNodes
    |           |-- selectorOnMesh
    |           |   `-- $current_sensor
    |           `-- group
    |               |-- $diameter[@type=edge]
    |               |-- $inside[@type=volume]
    |               `-- $skin[@type=face]
    |-- floatingType/
    |   `-- $current
    `-- outputRequest/
        `-- $outputRequest_group/
            `-- $or1[@subject=/label/predefinedOutputRequests
                     @subject_id=4
                     @object=/mesh/$gmesh1/$sphere/selectorOnMesh/$current_sensor
                     @output=/floatingType/$current]

and ``data.h5:/mesh/$gmesh1/$sphere/selectorOnMesh/$current_sensor``

======= ==== ==== ====
 index   v1   v2   v3
------- ---- ---- ----
  23     0    0    0
======= ==== ==== ====




Here is an example with a network structure :

::

    data.h5
    |-- label/
    |   `-- predefinedOutputRequests
    |-- mesh/
    |   `-- $gmesh1
    |       |-- $tl1
    |       `-- $tubes
    |           |-- nodes
    |           |-- elementTypes
    |           |-- elementNodes
    |           |-- selectorOnMesh
    |           |   `-- $current_sensor
    |           `-- group
    |               `-- $tube1[@type=element
    |                          @elementType=edge]
    |-- transmissionLine/
    |   `-- $tl1
    |-- outputRequest/
    |   `-- $outputRequest_group/
    |       `-- $or1[@subject=/label/predefinedOutputRequests
    |                @subject_id=4
    |                @object=/mesh/$gmesh1/$sphere/selectorOnMesh/$current_sensor
    |                @output=/floatingType/$current
    |                @idWire=2]
    |-- floatingType/
    |    `-- $current
    `-- network/
        `-- $net1[@type=simple]
            |-- tubes
            |-- junctions
            `-- connections

and ``data.h5:/mesh/$gmesh1/$sphere/selectorOnMesh/$current_sensor``

======= ==== ==== ====
 index   v1   v2   v3
------- ---- ---- ----
  23     0    0    0
======= ==== ==== ====




Wire voltage
############

::

    data.h5
    |-- label/
    |   `-- predefinedOutputRequests
    |-- mesh/
    |   `-- $gmesh1
    |       `-- $sphere
    |           |-- nodes
    |           |-- elementTypes
    |           |-- elementNodes
    |           |-- selectorOnMesh
    |           |   `-- $voltage_sensor
    |           `-- group
    |               |-- $diameter[@type=edge]
    |               |-- $inside[@type=volume]
    |               `-- $skin[@type=face]
    |-- floatingType/
    |   `-- $voltage
    `-- outputRequest/
        `-- $outputRequest_group/
            `-- $or1[@subject=/label/predefinedOutputRequests
                     @subject_id=5
                     @object=/mesh/$gmesh1/$sphere/selectorOnMesh/$voltage_sensor
                     @output=/floatingType/$voltage]

and ``data.h5:/mesh/$gmesh1/$sphere/selectorOnMesh/$voltage_sensor``

======= ==== ==== ====
 index   v1   v2   v3
------- ---- ---- ----
 23      0    0    0
======= ==== ==== ====


Wire Power
##########


::

    data.h5
    |-- label/
    |   `-- predefinedOutputRequests
    |-- mesh/
    |   `-- $gmesh1
    |       `-- $sphere
    |           |-- nodes
    |           |-- elementTypes
    |           |-- elementNodes
    |           |-- selectorOnMesh
    |           |   `-- $power_sensor
    |           `-- group
    |               |-- $diameter[@type=edge]
    |               |-- $inside[@type=volume]
    |               `-- $skin[@type=face]
    |-- floatingType/
    |   `-- $power
    `-- outputRequest/
        `-- $outputRequest_group/
            `-- $or1[@subject=/label/predefinedOutputRequests
                     @subject_id=6
                     @object=/mesh/$gmesh1/$sphere/selectorOnMesh/$power_sensor
                     @output=/floatingType/$power]

and ``data.h5:/mesh/$gmesh1/$sphere/selectorOnMesh/$power_sensor``

======= ==== ==== ====
 index   v1   v2   v3
------- ---- ---- ----
 23      0    0    0
======= ==== ==== ====



Bundle Current
##############

To request the current on a cable bundle :

::

    data.h5
    |-- label/
    |   `-- predefinedOutputRequests
    |-- mesh/
    |   `-- $gmesh1
    |       |-- $tl1
    |       `-- $tubes
    |           |-- nodes
    |           |-- elementTypes
    |           |-- elementNodes
    |           |-- selectorOnMesh
    |           |   `-- $current_sensor
    |           `-- group
    |               `-- $tube1[@type=element
    |                          @elementType=edge]
    |-- transmissionLine/
    |   `-- $tl1
    |-- outputRequest/
    |   `-- $outputRequest_group/
    |       `-- $or1[@subject=/label/predefinedOutputRequests
    |                @subject_id=4
    |                @object=/mesh/$gmesh1/$tubes/selectorOnMesh/$current_sensor
    |                @output=/floatingType/$current]
    |-- floatingType/
    |   `-- $current
    `-- network/
        `-- $net1[@type=simple]
            |-- tubes
            |-- junctions
            `-- connections

and ``data.h5:/mesh/$gmesh1/$sphere/selectorOnMesh/$current_sensor``

====== ==== ==== ====
index   v1   v2   v3
------ ---- ---- ----
 23      0   0    0
====== ==== ==== ====


No wire is specified.





Bundle Power
############

To request the power on a cable bundle :

::

    data.h5
    |-- label/
    |   `-- predefinedOutputRequests
    |-- mesh/
    |   `-- $gmesh1
    |       |-- $tl1
    |       `-- $tubes
    |           |-- nodes
    |           |-- elementTypes
    |           |-- elementNodes
    |           |-- selectorOnMesh
    |           |   `-- $power_sensor
    |           `-- group
    |               `-- $tube1[@type=element
    |                          @elementType=edge]
    |-- transmissionLine/
    |   `-- $tl1
    |-- outputRequest/
    |   `-- $outputRequest_group/
    |       `-- $or1[@subject=/label/predefinedOutputRequests
    |                @subject_id=6
    |                @object=/mesh/$gmesh1/$tubes/selectorOnMesh/$power_sensor
    |                 @output=/floatingType/$power]
    |-- floatingType/
    |   `-- $power
    `-- network/
        `-- $net1[@type=simple]
            |-- tubes
            |-- junctions
            `-- connections


and ``data.h5:/mesh/$gmesh1/$sphere/selectorOnMesh/$power_sensor`` :

====== ==== ==== ====
 index  v1   v2   v3
------ ---- ---- ----
 23      0   0    0
====== ==== ==== ====


No wire is specified.




Electric port
^^^^^^^^^^^^^

Port current
############

To request the current at a given port :

::

    data.h5
    |-- label/
    |   `-- predefinedOutputRequests
    |-- physicalModel/
    |   `-- multiport
    |       |-- $j1
    |       `-- $j2
    |-- floatingType/
    |   `-- $current
    |-- outputRequest/
    |    `-- $outputRequest_group/
    |        `-- $or1[@subject=/label/predefinedOutputRequests
    |                 @subject_id=4
    |                 @object=/network/$net1/junctions
    |                 @object_id=$j1
    |                 @output=/floatingType/$current
    |                 @idPort=2]
    `-- network/
        `-- $net1[@type=simple]
            |-- tubes
            |-- junctions
            `-- connections

The multi port is a junction : ``/network/$net1/junctions#$j1`` and the
port number is 2 :

========= ========= =======================================
  id        nbPort    multiport
========= ========= =======================================
  $j1         2      /physicalModel/multiport/$j1
  $j2         2      /physicalModel/multiport/$j2
========= ========= =======================================



Port voltage
############

To request the voltage at a given port :

::

    data.h5
    |-- label/
    |   `-- predefinedOutputRequests
    |-- physicalModel/
    |   `-- multiport
    |       |-- $j1
    |       `-- $j2
    |-- floatingType/
    |   `-- $voltage
    |-- outputRequest/
    |    `-- $outputRequest_group/
    |        `-- $or1[@subject=/label/predefinedOutputRequests
    |                 @subject_id=5
    |                 @object=/network/$net1/junctions
    |                 @object_id=$j1
    |                 @output=/floatingType/$voltage
    |                 @idPort=2]
    `-- network/
        `-- $net1[@type=simple]
            |-- tubes
            |-- junctions
            `-- connections

The multi port is a junction : ``/network/$net1/junctions#$j1`` and the
port number is 2.

========= ========= =======================================
  id        nbPort    multiport
========= ========= =======================================
  $j1         2      /physicalModel/multiport/$j1
  $j2         2      /physicalModel/multiport/$j2
========= ========= =======================================


Port Power
##########

To request the voltage at a given port :

::

    data.h5
    |-- label/
    |   `-- predefinedOutputRequests
    |-- physicalModel/
    |   `-- multiport
    |       |-- $j1
    |       `-- $j2
    |-- floatingType/
    |   `-- $current
    |-- outputRequest/
    |    `-- $outputRequest_group/
    |        `-- $or1[@subject=/label/predefinedOutputRequests
    |                 @subject_id=6
    |                 @object=/network/$net1/junctions
    |                 @object_id=$j1
    |                 @output=/floatingType/$current
    |                 @idPort=2]
    `-- network/
        `-- $net1[@type=simple]
            |-- tubes
            |-- junctions
            `-- connections

The multi port is a junction : ``/network/$net1/junctions#$j1`` and the
port number is 2 :


========= ========= =======================================
  id        nbPort    multiport
========= ========= =======================================
  $j1         2      /physicalModel/multiport/$j1
  $j2         2      /physicalModel/multiport/$j2
========= ========= =======================================



Total current
#############

::

    data.h5
    |-- label/
    |   `-- predefinedOutputRequests
    |-- physicalModel/
    |   `-- multiport
    |       |-- $j1
    |       `-- $j2
    |-- floatingType/
    |   `-- $current
    |-- outputRequest/
    |    `-- $outputRequest_group/
    |        `-- $or1[@subject=/label/predefinedOutputRequests
    |                 @subject_id=4
    |                 @object=/network/$net1/junctions
    |                 @object_id=$j1
    |                 @output=/floatingType/$current]
    `-- network/
        `-- $net1[@type=simple]
            |-- tubes
            |-- junctions
            `-- connections


``data.h5:/network/$net1/junctions#$j1`` is :

========= ========= =======================================
  id        nbPort    multiport
========= ========= =======================================
  $j1         2      /physicalModel/multiport/$j1
  $j2         2      /physicalModel/multiport/$j2
========= ========= =======================================


No wire is specified.


Total power
###########


::

    data.h5
    |-- label/
    |   `-- predefinedOutputRequests
    |-- physicalModel/
    |   `-- multiport
    |       |-- $j1
    |       `-- $j2
    |-- floatingType/
    |   `-- $power
    |-- outputRequest/
    |    `-- $outputRequest_group/
    |        `-- $or1[@subject=/label/predefinedOutputRequests
    |                 @subject_id=6
    |                 @object=/network/$net1/junctions
    |                 @object_id=$j1
    |                 @output=/floatingType/$power]
    `-- network/
        `-- $net1[@type=simple]
            |-- tubes
            |-- junctions
            `-- connections


``data.h5:/network/$net1/junctions#$j1`` is :

========= ========= =======================================
  id        nbPort    multiport
========= ========= =======================================
  $j1         2      /physicalModel/multiport/$j1
  $j2         2      /physicalModel/multiport/$j2
========= ========= =======================================


No wire is specified.



Equivalent circuit
^^^^^^^^^^^^^^^^^^

S parameters
############

Z parameters
############

Y parameters
############


Thevenin voltage generator
##########################

Norton current generator
########################

Voltage and current generators
##############################            


3D object power absorption capabability
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Coupling cross-section
######################