.. _accessSuper:

================
**Superelement**
================

.. role:: red
.. role:: big
	  
Befehle, die das Lesen und Zuweisen der Werte und Eigenschaften von Superelementen 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                                                                |
+------------+--------------+---------+-----------------+-----------------------------------------------------------------------+
|srkey       | 1            | -       | g               | Nummer der übergeordneten Subregion                                   |
+------------+--------------+---------+-----------------+-----------------------------------------------------------------------+
|elkeys      | [N]          | -       | g               | Nummern aller N Elemente des Superelements                            |
+------------+--------------+---------+-----------------+-----------------------------------------------------------------------+
|ndkeys      | [N]          | -       | g               | Nummern aller N Knoten die das Superelement beinhaltet                |
+------------+--------------+---------+-----------------+-----------------------------------------------------------------------+
|ndchn       | [N]          | -       | g               | Nummern aller N Knotenketten die das Superelement beinhaltet          |
+------------+--------------+---------+-----------------+-----------------------------------------------------------------------+
|bndkeys     | [N]          | -       | g               | Nummern aller N Randknoten des Superelements                          |
+------------+--------------+---------+-----------------+-----------------------------------------------------------------------+
|col         | 1            | -       | g               | Farbe [1:255]                                                         |
+------------+--------------+---------+-----------------+-----------------------------------------------------------------------+
|mcvtyp      | 1            | -       | g               | Art der Magnetisierungskennlinie                                      |
+------------+--------------+---------+-----------------+-----------------------------------------------------------------------+
|condtyp     | 1            | -       | g               | Art des Leiters                                                       |
+------------+--------------+---------+-----------------+-----------------------------------------------------------------------+
|conduc      | 1            | S/m     | g/s             | Spezifische Leitfähigkeit                                             |
+------------+--------------+---------+-----------------+-----------------------------------------------------------------------+
|rlength     | 1            | -       | g/s             | Relative Länge                                                        |
+------------+--------------+---------+-----------------+-----------------------------------------------------------------------+
|velsys      | 2            | -       | g/s             | Bezugssystem der Geschwindigkeitsdefinition (cartes, polar, cylind)   |
+------------+--------------+---------+-----------------+-----------------------------------------------------------------------+
|velo        | 2            | m/s     | g/s             | Geschwindigkeit entlang Koordinate 1 und 2 des Bezugssystems "velsys" |
+------------+--------------+---------+-----------------+-----------------------------------------------------------------------+
|area        | 1            | gu²     | g               | Superelementfläche                                                    |
+------------+--------------+---------+-----------------+-----------------------------------------------------------------------+
|curd        | 2            | A/mm²   | g/s             | (Wirbel)stromdichte (Realteil, Imaginärteil)                          |
+------------+--------------+---------+-----------------+-----------------------------------------------------------------------+
|cur         | 2            | A       | g               | (Wirbel)strom (Realteil, Imaginärteil) im Superelement                |
+------------+--------------+---------+-----------------+-----------------------------------------------------------------------+
|curlos      | 1            | W/gu    | g               | (Wirbel)stromverluste (Mittelwert) im Superelement pro Längeneinheit  |
+------------+--------------+---------+-----------------+-----------------------------------------------------------------------+

gu = globale Längeneinheit


:big:`Befehlsbeschreibung`

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

.. admonition:: Function:   	*key* 	  =   	get_spel_key 	( 	*x, y* 	 ) 
	
 Gibt die Nummer eines Superelementes zurück, das über die kartesischen Koordinaten x und y adressiert wird.

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

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

 Beispiel
 ::

  key = get_spel_key(x,y)              -- Get the superelement's number
  print("super-element key = %d",key)  -- Output to shell

.. admonition:: Command:   	get_spel_keys 	( 	*x, y, "var"* 	 ) 
	
 Gibt die Nummern aller Superelemente einer Subregion zurück. Die Subregion 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 Superelementnummern zurückgegeben werden

 Beispiel
 ::

  get_spel_keys(x,y,"keys")  -- Get all superelements of the subregion addressed by x,y
  N = table.getn(keys)       -- Number of elements in array

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

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

 Beispiel
 ::

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

.. admonition:: Function:   	*d1, d2, ...* 	  =   	get_spel_data 	( 	*"identifier", key* 	 ) 
	
 Liest Daten eines Superelementes und gibt diese zurück.

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

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

 Beispiel: Ermittlung der Fläche eines Superelements
 ::

  A = get_spel_data("area",key) 

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

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

.. admonition:: Command:   	set_spel_data 	( 	*"identifier", key, d1, d2, ...* 	 ) 
	
 Weist einem Superelement die angegebenen Eigenschaften zu.

 **Parameter**
  | :red:`identifier`	Art der zuzuweisenden Eigenschaft (siehe Tabelle)
  | :red:`key` Superelement number
  | :red:`d1` First refering value
  | :red:`d2` Second refering value

 Beispiel: Vorgabe der Stromdichte eines Superelements
 ::

  set_spel_data("curd",key,4.24,1.5)

Anwendungsbeispiel
^^^^^^^^^^^^^^^^^^

Ermittlung der Nummern aller in einer Subregion enthaltenen Superelemente und zyklisches Lesen einer Größe, hier die Fläche der Superelemente.
::

  get_spel_keys(x,y,"keys")     -- get all superelememt keys in subregion addressed by x,y    
  N = table.getn(keys)          -- number of keys
  for i=1,N do
    draw_spel(keys[i],"red",0)          -- draw considered superelement
    A = get_spel_data("area",keys[i])   -- get property of superelement
    printf("%d %g",i,A)                 -- output result to shell
  end


Rückgabe der Randknoten und Darstellung der Kontur eines Superelements.
::

  bndkeys = get_spel_data("bndkeys",x0,y0)       -- get all boarder node keys
  grf_clear()
  for j=1,#bndkeys-1 do                          -- loop over all keys
    x1,y1 = get_node_data("xy",bndkeys[j])       -- get the node coordinates
    x2,y2 = get_node_data("xy",bndkeys[j+1])
    point(x1,y1,"black","x")                     -- draw nodes
    line(x1,y1,x2,y2,"black")                    -- draw the contour
    text(x1,y1,tostring(bndkeys[j]),"black",0.1) -- print node numbers
  end
  x1,y1 = get_node_data("xy",bndkeys[1])         -- add the last node and close contour
  point(x2,y2,"black","x")
  line(x1,y1,x2,y2,"black")
  text(x2,y2,tostring(bndkeys[#bndkeys]),"black",0.1)