.. _check_installation_src:

Check Installation
====================

In this tutorial we will check if openEMS is correctly installed.

After completion of this tutorial, there is confidence in the correct installation of openEMS.

Prerequisites
-------------------

* Installed openEMS (refer to :ref:`clone_build_install_src` and :ref:`install_readymade_package_src`)
* Matlab / Octave
* Python

openEMS executable
----------------------

First lets check, if the openEMS executable is correctly installed (there may be
missing dependencies or an incompatible architecture):

Linux
^^^^^^^^^

1. Open a terminal window
2. Invoke the openEMS solver

.. code-block:: console

    $ openEMS

The output should be similar to:

.. code-block:: console

     ---------------------------------------------------------------------- 
     | openEMS 64bit -- version v0.0.33
     | (C) 2010-2015 Thorsten Liebig <thorsten.liebig@gmx.de>  GPL license
     ---------------------------------------------------------------------- 
    [...]

If the command is not found, please include the folder to the openEMS installation
directory (such as `/home/user/openEMS-bin/bin`) to your search path.


Windows
^^^^^^^^

1. open a command window ("Start"-Button, type "cmd")
2. change the current folder to the openEMS installation directory
3. invoke the openEMS solver

.. code-block:: console

    openEMS

The output should be similar to:

.. code-block:: console

     -------------------------------------------------------------------- 
     | openEMS 32bit -- version v0.0.23
     | (C) 2010 Thorsten Liebig <thorsten.liebig@gmx.de>  GPL license
     --------------------------------------------------------------------
    [...]

AppCSXCAD executable
----------------------

The AppCSXCAD program graphically displays the structure built by
Matlab/Octave or Python scripts. It is very useful to visualize the
computational area and helps to find errors in the geometrical
definition of the structure.

Linux
^^^^^^^^^

1. Open a terminal window
2. Invoke AppCSXCAD

.. code-block:: console

    $ AppCSXCAD

You should be able to see the AppCSXCAD window on your desktop.

If the command is not found, please include the folder to the openEMS installation
directory (such as `/home/user/openEMS-bin/bin`) to your search path.

Windows
^^^^^^^^^

1. open a command window ("Start"-Button, type "cmd")
2. change the current folder to the openEMS installation directory
3. invoke AppCSXCAD

.. code-block:: console

    AppCSXCAD

You should be able to see the AppCSXCAD window on your desktop.

Matlab/Octave Interface
------------------------

openEMS needs a xml-file to start the simulation. This file is normally generated by
Matlab (or Octave).

- start Matlab (or Octave)

Now let's check if the CSXCAD interface functions are available, type the following into
the command window and compare the output:

.. code-block:: console

    >> InitCSX
    
    ans = 
    
        Properties: []

If the error message states 'InitCSX' is undefined, you need to have another look at
the install instructions:

Now let's check if the openEMS interface functions are available:

.. code-block:: console

    >> InitFDTD('NrTS', 0, 'EndCriteria', 0)
    
    ans = 
    
        ATTRIBUTE: [1x1 struct]

If the error message states 'InitFDTD' is undefined, you need to have another look at
the install instructions:

Let's try to start the simulator from our Matlab environment:

.. code-block:: console

    >> RunOpenEMS( '.', 'nonexistant.xml', '' )
    [...]
    Read openEMS xml file: nonexistant.xml ...
    openEMS: Error File-Loading failed!!! File: nonexistant.xml

Although it presents an error message, the call itself was successful. Matlab is able to find
the simulator executable and start it with the name of the xml-file.

Python interface
------------------

- start Python

Now let's check if the CSXCAD and openEMS interface functions are available, type the
following into the command window and compare the output:

.. code-block:: console

    >>> import CSXCAD
    >>> import openEMS

If there's no output, such as a `ModuleNotFoundError`, it means Python can successfully
find and import the required modules.

Note that you should run Python from you home directory or another location, it should
not be ran inside the `python` directory of the CSXCAD or openEMS source code tree.
Otherwise, Python will attempt to use the `CSXCAD` or `openEMS` files in the source
code as Python modules, creating confusing errors.