=======================
**Single calculations**
=======================

.. admonition:: Command: calc_field_single(*maxit, permode, maxcop, freq*)

 Perform a single field calculation. 
		
 **Parameter**
  | *maxit*      Maximum number of iterations, (1 for linear calculation)
  | *rmod*       Reset the permeability with restored, maintaining the current with *actual*
  | *du_u0*      Cancellation condition (lower limit for change in permeability in %)
  | *freq*       Frequency [Hz] for FEMAG-AC (optional parameter, from Rev. 8.2)

 **Example**
 ::
    
  calc_field_single(99,actual,0.05)          -- deprecated version
  calc_field_single(99,"actual",0.05)

 When calling the function without arguments the global settings for maxit, rmod and du_u0 are used (see FE Control Parameter)::
   
  calc_field_single()

 In newer FEMAG-versions the call is clearer , as the following example shows::
   
  Bei neueren FEMAG-Versionen ist der Aufruf anschaulicher durch Übergabe der Argumente als Datenstruktur möglich, wie das nachfolgende Beispiel verdeutlicht.

  calc_field_single({
                      maxit   = 99,        -- max number of iterations (default: 1 => linear calculation) 
                      maxcop  = 0.05,      -- max change of permeability (default: 0.1
                      permode = "act",     -- permeability mode ("actual", "restored", default: "restored")
                      freq = 0.0           -- frequency in case of FEMAG AC (default: 0)
                    })

 The order of the arguments is without relevance and furthermore are they optional. Each default value are is given in the example.The identifier in quotation marks can generaly be used in shortened form as well, e.g. *"act"* instead of *"actual"*.

 See example :any:`exampleCoil`

.. admonition:: Command: calc_demag(*dmod, hkrit*)
		
 Execute a demagnetization calculation. The routine must be called several times until the magnetization state is stationary, so this command is actually executing an iteration step.

 **Parameter**
  | *dmod* Demagnetization model 
  | *hkrit* Demagnetization critical field

 **Demagnetization models** 

 * dmod = 1: the model used in ''Multiple-Calculations-I/''.  For anisotropic permanent magnets, only the field component in the direction of the magnetization vector is considered. The linear model is defined by the remanent flux-density and relative recoil permeability. The field strength *hkrit* defines the knee point. Calculation is on a parallel to the magnetization characteristic.


.. admonition:: Command: rotate(*agr, phi, dsel, mode*)
		
 Rotation of the inner or outer part of a machine by a predetermined absolute or incremental angle *phi*. The *mode* parameter can be used to set the mode of rotation or the function of the routine. *Save* and *reset* save or restore the initial state. Other parameters have no meaning here. The default *absolute* rotates the rotor from the initial state around the specified absolute angle *phi*. The material properties are reset at each rotation step. The default *increment* rotates to restore an angular increment *phi* without first restoring the initial state.

 **Parameter**
  | *agr* Air-gap radius
  | *phi* The angle of rotation [deg]
  | *dsel* Selects the machine part to be moved (*"inside"*, *"outside"*)
  | *mode* Selects the mode (*"absolute"*, *"increment"*, *"save"*, *"reset"*)

 **Example**
 ::

  rotate(27,12,inside,absolute)         -- deprecated version
  rotate(27,12,"inside","absolute")

 Dreht den inneren Bereich des Modells abgegrenzt durch den mittleren Luftspalt mit einem Radius von 27 mm von der Ausgangslage um 12° in mathematisch positive Richtung.

 ..
  translate

 See example :any:`exampleCoil`

 Bei neueren FEMAG-Versionen ist der Aufruf in erweiterter Art möglich. Die Übergabe der Argumente erfolgen als Datenstruktur, wie das nachfolgende Beispiel verdeutlicht. Der Aufruf ist dreigeteilt in eine Initialisierung, die eigentliche Drehung und das Rücksetzen des Modells nach Abschluss des Bewegungsablaufs. Diese Teilung ermöglicht eine schnellere Ausführung der Drehung, da Prüfungen des Modells lediglich bei der Initialisierung erfolgen. Beim herkömmlichen Aufruf wie oben gezeigt, erfolgen diese bei jedem Drehschritt und verlangsamen.

 ..
  translate

 **Example**: Initializing
 ::
    
  rotate({
           airgap = 27,        -- air gap radius
           region = "inside",  -- region to rotate ("inside" or "outside")
           mode   = "save",    -- save the initial model state
           quant  = 2.0        -- quantization of rotation angle in degree
         })

 The argument *quant* is optional. Default value of the quantization is 1° to prevent impact from rounding errors.

 **Example:** Rotation
 ::

  rotate({
           angle = phi,        -- angle of rotation
           mode  = "abs",      -- type of movement ("absolute" or "incremental")
           check = "auto",     -- type of internal checks to perform ("all", "auto" or "none")
         })

 Identifier in quotations marks can be used in shortened form, e.g. *"abs"* instead of *"absolute"*. The argument is optional, default value is *"auto"*.

 **Example:** Reset after closure
 ::
    
  rotate({
           mode = "reset"      -- restore the initial state (discard any changes)
         })

 See example **eg_pocfileVerwendung von poc-Files in individuellen Berechnungsabläufen**

 ..
  add link

.. admonition:: Command: read_poc_file(*file, steps, curr, curr_angle*)

 Opens a poc-file with electrical current definitions for the later uses in combination with the command *update_curr_pos*.

 **Parameter**
  |  *file* name of the poc-file with extension 
  |  *steps* amount of movement steps including first and last
  |  *curr* current peak value 
  |  *currangle* current angle (phase position opposite to polrad voltage, optional, default value is 0)

 **Example**
 ::
    
  read_poc_file("example_10p.poc",72+1,30,-20)


Im Beispiel beträgt die doppelte Polteilung 72° (elektrischer Periodenwinkel). Es soll in Schritten von 1° gedreht werden. Der Drehbereich umfasst eine gesamte Periode, der erste Drehschritt enspricht dem letzten. Es werden daher 72+1 Positionen berechnet. Die Stromamplitude beträgt 30 A und der Strangstrom eilt der Polradspannung um 20° vor. Die Definition der Schrittanzahl und des Stromwinkels entsprechen somit der Multiple-I/x-Berechnung.

 ..
  translate

 See example **eg_pocfileVerwendung von poc-Files in individuellen Berechnungsabläufen** 

 ..
  add link

.. admonition:: Command: update_curr_pos(*step, curr_fact*)
		
 Verwendung nach vorangehendem Öffnen einer poc-Datei mit dem Befehl readpocfile. Der Aufruf aktualisiert die Strangströme für den vorgegebenen Bewegungsschritt step entsprechend der Verlaufsdefinition in der poc-Datei.

 ..
  translate

 **Parameter**
  | *step* movement step 
  | *currfact* factor of the given current (optional, default value is 1)

 **Example**
 ::
    
  phi, dphi = update_curr_pos(5) 

 This function returns the current position respectively the rotation agle *phi* and the angle increment *dphi*.

 See example **eg_pocfileVerwendung von poc-Files in individuellen Berechnungsabläufen**

 ..
  add link