============================
FSL  (FEMAG script language)
============================

The script interpreter is an integral part of FEMAG and allows you to define processes before FEMAG starts. The desired
FEMAG actions are programmed by the user in a text file (script file). For this purpose, a largely complete and
easy-to-learn programming language can be used.

The script interpreter programming language Lua.

+--------------+-------------------------------------------------------------------------+
| Overview:    | https://en.wikipedia.org/wiki/Lua_programming_language                  |
+--------------+-------------------------------------------------------------------------+
| Homepage:    | https://www.lua.org/                                                    |
+--------------+-------------------------------------------------------------------------+
| User manual: | https://www.lua.org/manual/5.4 *(versions before v2023.1 used Lua 5.3)* |
+--------------+-------------------------------------------------------------------------+

In addition to the range of commands from Lua, a FEMAG-specific function library is available. These can be used to
initiate actions that are known from the interactive operation via the program menu.

In the simplest case, the FEMAG script interpreter can be used to automate recurring processes during model creation
or model analysis. However, by defining its own functions  and libraries, it also allows a user-specific extension of
FEMAG. The script interpreter can also serve as a flexible interface for integrating FEMAG into an application-specific
design environment or interface.

FEMAG scripts always complete with the ".fsl" file extension.

Executing a FEMAG script is done by specifying the file name when calling FEMAG as an argument (with an ending) or via
the "Select Input File" and "Select Scriptfile" menus. See section :ref:`script`.

Feedback from the interpreter is logged in the FEMAG-FSL.jrn and FEMAG-FSL.log files during script execution. Causes of
errors are specified there with reference to the line number of the script.

.. _intro_handling:

Handling of global variables and optional parameters
----------------------------------------------------

Some function calls use global variables (parameters) which are optional, i.e. the assignment of permanent material
properties

.. sourcecode:: lua

 m.remanenc   =        1.200  -- Remanence Br (Ref: 20 Degree C)    [T]
 m.relperm    =        1.050  -- Relative permeability muer         [-]
 m.spmaweight =        7.600  -- Specific weight of magnets    [gr/cm3]
 m.temcoefbr  =       -0.100  -- Temperature coefficient for Br   [%/K]
 m.temcoefhc  =       -0.100  -- Temperature coefficient for Hc   [%/K]
 m.magntemp   =       20.000  -- Magnet temperature          [Degree C]
 m.magncond   =   625000.000  -- Magnet el. conductivity      [1/Ohm m]
 m.magsegwid  =       51.100  -- Magnet segment width              [mm]
 m.magseglen  =      120.000  -- Magnet segment length z-direction [mm]

 pre_models("Magnet-data")

To remove an already defined parameter or expilcitly declare it as unspecified use the nil assignment, e.g.

.. sourcecode:: lua

 m.remanenc   = nil

previously. Thus, currently existing remanence of the permanent magnets is maintained in this example.

Further information
-------------------

See also:

| Prozessintegration von FEMAG zur Automation des Entwurfs von PM-Motoren (J. Krotsch, 2007):
| https://www.profemag.ch/index.php/de/downloads/category/21-awt.html?download=288:2007
| FEMAG-Script: Stand und weitere Planung der Entwicklung (J. Krotsch, 2008):
| https://www.profemag.ch/index.php/de/downloads/category/22-awt-2008.html?download=304:2008