.. _accessSub:

=============
**Subregion**
=============

.. role:: red
.. role:: big
	  
Befehle, die das Lesen und Zuweisen der Werte und Eigenschaften von Subregionen ermöglichen.

Geometrische Größen (Koordinaten, Längen und Flächen) entsprechen der global gewählten Längeneinheit (gobal_unit, siehe :any:`settings`). Übergebene oder zurückgelieferte Vektoren (Komponenten der Vektoren) beziehen sich, wenn in der Funktionsbeschreibung nicht explizit angegeben, auf das kartesisches System. Zur einfachen Umrechnung zwischen unerschiedlichen Bezugssystemen stehen Funktionen zur :any:`trans` zur Verfügung.

:big:`Übersicht`

----------------------------------------------------------------------

+------------+--------------+---------+-----------------+------------------------------------------------------+
| Bezeichner | Anzahl Werte | Einheit | Zugriff get/set | Beschreibung                                         |
+------------+--------------+---------+-----------------+------------------------------------------------------+
| valid      | 1            | -       | g               | Gültigkeit                                           |
+------------+--------------+---------+-----------------+------------------------------------------------------+
| key        | 1            | -       | g               | Nummer der Subregion                                 |
+------------+--------------+---------+-----------------+------------------------------------------------------+
| type       | 1            | -       | g               | Typ der Subregion                                    |
+------------+--------------+---------+-----------------+------------------------------------------------------+
| col        | 1            | -       | g               | Farbe                                                |
+------------+--------------+---------+-----------------+------------------------------------------------------+
| sekeys     | [N]          | -       | g               | Nummern aller N Superelemente der Subregion          |
+------------+--------------+---------+-----------------+------------------------------------------------------+
| wbkey      | 1            | -       | g               | Nummer der Wicklung zu der die Subregion gehört      |
+------------+--------------+---------+-----------------+------------------------------------------------------+
| nturns     | 1            | -       | g               | Leiterzahl                                           |
+------------+--------------+---------+-----------------+------------------------------------------------------+
| area       | 1            | gu²     | g               | Fläche der Subregion                                 |
+------------+--------------+---------+-----------------+------------------------------------------------------+
| curdir     | 1            | -       | g               | Stromrichtung bzw. Wickelsinn                        |
+------------+--------------+---------+-----------------+------------------------------------------------------+
| cur        | 2            | A       | g               | (Wirbel)strom (Realteil, Imaginärteil)               |
+------------+--------------+---------+-----------------+------------------------------------------------------+
| curd       | 2            | A/mm²   | g               | (Wirbel)stromdichte (Realteil, Imaginärteil)         |
+------------+--------------+---------+-----------------+------------------------------------------------------+
| curlos     | 1            | W/gu    | g               | (Wirbelstrom)verluste (Mittelwert) pro Längeneinheit |
+------------+--------------+---------+-----------------+------------------------------------------------------+
| volt       | 2            | V/gu    | g               | Spannung (Realteil, Imaginärteil)                    |
+------------+--------------+---------+-----------------+------------------------------------------------------+
| rlength    | 1            | -       | s               | Relative Länge                                       |
+------------+--------------+---------+-----------------+------------------------------------------------------+

gu = globale Längeneinheit


:big:`Befehlsbeschreibung`

----------------------------------------------------------------------

.. admonition:: Function:   	*key* 	  =   	get_sreg_key 	( 	*x, y* 	 ) 

 Gibt die Nummer einer Subregion zurück, die über die kartesischen Koordinaten x und y adressiert wird.

 **Parameter**
  | [in] :red:`x` Coordinate 1
  | [in] :red:`y` Coordiante 2

 **Return values**
  :red:`key` Subregion number

 Beispiel
 ::

  key = get_sreg_key(x,y)          -- Get the subregion number
  print("subregion key = %d",key)  -- Output to shell


.. admonition:: Command:   	get_sreg_keys 	( 	*x, y, "var"* 	 ) 
	
 Gibt die Nummern aller Subregionen einer Wicklung zurück. Die Wicklung wird über die kartesischen Koordinaten x und y adressiert.

 **Parameter**
  | [in]  :red:`x` Coordinate 1
  | [in]  :red:`y` Coordiante 2
  | [out]  :red:`var` Bezeichner des Arrays in dem die Subregionnummern zurückgegeben werden

 Beispiel
 ::

  get_sreg_keys(x,y,"keys")  -- Get all subregions of the winding addressed by x,y
  N = table.getn(keys)       -- Number of elements in array

.. admonition:: Command:   	get_sreg_keys 	( 	*"var"* 	 ) 
	
 Gibt die Nummern aller Subregionen des Modells zurück.

 **Parameter**
    [out] :red:`var` Bezeichner des Arrays in dem die Subregionnummern zurückgegeben werden

 Beispiel
 ::

  get_sreg_keys("keys")      -- Get all subregions of the model
  N = table.getn(keys)       -- Number of elements in array

.. admonition:: Function:   	d1, d2, ... 	  =   	get_sreg_data 	( 	*"identifier", key* 	 ) 
	
 Liest Daten einer Subregion und gibt diese zurück.

 **Parameter**
  | [in] :red:`identifier` Art der auszulesenden Daten (siehe Tabelle)
  | [in] :red:`key` Subregion number

 **Return values**
  | :red:`d1` First return value
  | :red:`d2` Secodn return value

 Beispiel: Ermittlung der Fläche einer Subregion
 ::

  A = get_sreg_data("area",key) 

 Alternativ zu key kann die Subregion auch über kartesische Koordinaten in der globalen Einheit adressiert werden.
 ::

  A = get_sreg_data("area",x,y) 

.. admonition:: Command:   	set_sreg_data 	( 	*"identifier", key, d1, d2, ...* 	 ) 
	
 Weist einer Subregion die angegebenen Eigenschaften zu.

 **Parameter**
  | [in] :red:`identifier` Art der zuzuweisenden Eigenschaft (siehe Tabelle)
  | [in] :red:`key` Subregion number
  | [in] :red:`d1` Firsrt refering value
  | [in] :red:`d2` Second refering value (optional)

 Beispiel: Vorgabe der relativen Längen eines Superelements von 125%
 ::

  set_sreg_data("rlength",key,1.25)