.. _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 (see :ref:`clone_build_install_src` and :ref:`install_readymade_package_src`)
* Matlab / Octave (see :ref:`octave_install`)
* Python (see :ref:`pyinstall`)

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 ``~/opt/openEMS/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 ``~/opt/openEMS/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

.. important::

   If Python dependencies were installed into a ``venv``, activate
   the ``venv`` first. Assume the ``venv`` is located in
   ``$HOME/opt/openEMS/venv/bin``.

   .. code-block:: bash

       source $HOME/opt/openEMS/venv/bin/activate

Now let's check if the CSXCAD and openEMS interface functions are available.
First, switch to a neutral directory such as ``/`` or ``~/``. Don't test
Python extensions in the source code directories (``CSXCAD/python``,
``openEMS/python``), otherwise, Python will attempt to use uncompiled
source code files as Python modules, creating confusing errors.

.. code-block:: console

    $ cd /  # Important: always leave "python" first.

Next, type the following into the command window and compare the
output:

.. code-block:: console

    $ cd / && python3 -c "import CSXCAD; print(CSXCAD.ContinuousStructure())"
    <CSXCAD.CSXCAD.ContinuousStructure object at 0x7f5957943fd0>

    $ cd / && python3 -c "import CSXCAD; print(CSXCAD.__version__)"
    0.6.4.dev76+gccb4c218e

    $ cd / && python3 -c "import openEMS; print(openEMS.openEMS())"
    <openEMS.openEMS.openEMS object at 0x7f47f8dffb20>

    $ cd / && python3 -c "import openEMS; print(openEMS.__version__)"
    '0.0.36.post1.dev115+gfbb03a107.d20251112'

If the expected outputs are shown without errors (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.