.. _gseimorg:

==================
GSEIM Organisation
==================

In this section, we describe how the GSEIM program is
organised. We will use the following to denote the
various directories involved:

- ``$GSEIM_MASTER`` **:** the ``/gseim-master`` directory in
  the GSEIM distribution (see :ref:`Getting started <getting_started>`)

- ``$BLOCKS`` **:** ``$GSEIM_MASTER/gseim_grc/src/gseim/data/blocks``

- ``$XBE`` **:** ``$GSEIM_MASTER/gseim_grc/src/gseim/data/xbe``

- ``$EBE`` **:** ``$GSEIM_MASTER/gseim_grc/src/gseim/data/ebe``

- ``$GRC`` **:** ``$GSEIM_MASTER/gseim_grc/src/grc``

  (``grc`` stands for GNU Radio Companion, part of the
  `GNU Radio <https://www.gnuradio.org//>`_ package. Files in ``$GRC``
  are originally from GNU Radio Companion, modified suitably for GSEIM.)

- ``$GSEIM`` **:** ``$GSEIM_MASTER/gseim_grc/src/gseim``

- ``$CPPSRC`` **:** ``$GSEIM_MASTER/gseim_grc/src/gseim_cpp_lib``

- ``$PLOT`` **:** ``$GSEIM_MASTER/gseim_grc/src/gseim_plot``

- ``$SUBCKT`` **:** ``$GSEIM_MASTER/gseim_grc/src/gseim/data/subckt``

- ``$SUBCKT_GRC`` **:** ``$GSEIM_MASTER/gseim_grc/src/gseim/data/subckt_grc``

The block diagram of the GSEIM program is shown below. When
applicable, the location (directory) of the concerned block
is also given.

.. image:: block_1.png
  :width: 550
  :alt: Alternative text

The program components can be broadly classified as follows.

- **Schematic entry GUI**: This block consists of python
  files adapted from the `GNU Radio <https://www.gnuradio.org//>`_ package.
  It enables the user to prepare a schematic diagram of the system of
  interest, and as output, it produces a high-level netlist in the
  GNU Radio format. The high-level netlist (with extension ``.grc``),
  which we will refer to as the **project file**, can be saved by
  the user in a directory of their choice using the ``save file`` button.
  We will refer to this directory as ``$GRC_FILE_DIR``.

- **Parser**: This is a python program, ``$GSEIM/gseim_parser.py``, which
  takes the high-level netlist (the ``.grc`` file)
  as input, and performs parsing of node names and computation
  of element parameters (if applicable). As its output, the
  parser produces a low-level netlist (with extension ``.in``)
  in ``$GRC_FILE_DIR``.
  We will refer to this low-level netlist as the **circuit file**.

- **Solver**: This part of the code, written in C++, performs
  numerical solution of the circuit equations and ODEs represented by
  the user's schematic. It takes the low-level netlist (the circuit file)
  as its input, and creates the output files requested by the user
  in ``$GRC_FILE_DIR``.

- **Plotting GUI**: This is a python-Qt program for showing
  plots using the data files generated by the solver.

- **Element library**: GSEIM has been designed to completely
  decouple the element library from the solver, which makes it
  possible for the user to add new elements to the library (if
  required). For each element ``xyz``, the library contains
  the following files:

  - If ``xyz`` is a flow-graph type element, the file ``xyz.xbe``
    contains information about the variable names, parameter
    names and values, and equations related to that element.

  - If ``xyz`` is an electrical type element, the file ``xyz.ebe``
    contains information about the node names, parameter
    names and values, and equations related to that element.

  - For both flow-graph and electrical type elements, the
    file ``xyz.yml`` specifies how the element would appear
    in the schematic entry GUI.

  The ``.xbe`` and ``.ebe`` files are used by both the
  schematic entry GUI and the solver whereas the ``.yml``
  files are used only by the schematic entry GUI.

- **Subcircuits (hierarchical blocks)**: In several applications,
  subcircuits (hierarchical blocks) are convenient. A few subcircuits
  are provided with the GSEIM distribution. Files related to subcircuits
  are located in ``$SUBCKT`` and ``$SUBCKT_GRC``.
  Apart from that, the user can also make up new subcircuits, as
  described in the :ref:`Subcircuits <subckt>` section.