Engee documentation

Engee system objects

This article describes a general approach to working with system objects in Engee. For help with a specific system object, go to command line of Engee img 41 1 2 and in help mode? (click ? to enter the mode) enter its name.

A System Object is an object in the Engee modelling environment that helps to model dynamic systems. System objects are particularly useful for signal processing, communications, radar, and control applications. They provide modularity and convenience when creating dynamic systems in Engee by providing a simple means of creating, configuring and usage of components.

The usage of system objects allows real-world objects to be modelled using object-oriented programming (OOP) principles. This provides a smooth transition from engineering concepts to software models, which allows to organise work with objects more efficiently in accordance with classical programming approaches.

System objects are created and used in four stages:

so diagram 1

  1. Creating components - the first stage involves initialising system objects that represent the required system components. These objects can model signal generators, transmitters, receivers and other devices. For example, a waveform object is created using the EngeePhase.RectangularWaveform() class to represent a rectangular pulse generator. At this stage, blanks for future components are created, but not yet without detailed customisation;

  2. Component configuration - once the object is created, it is configured, where key parameters are set that determine the behaviour of the component. This may include pulse repetition rate, signal power, sampling rate and other important characteristics;

  3. Assembly of components into a system - at this stage the configured components are assembled into a single system where they can interact with each other to create a data stream. This assembly allows you to organise the transmission and processing of signals between components, reflecting the physical processes that will occur when the system is operating;

  4. System Startup - Once the component assembly is complete, the system is ready for operations. At this stage, all necessary calculations and signalling are performed.

Example of starting a radar system based on system objects (for more details see '''''). Stages of creating a system based on system objects):

# Создание генератора сигнала (первый этап)
waveform = EngeePhased.RectangularWaveform()

# Настройка генератора сигнала (второй этап)
waveform.PulseWidth = 100e-6;   # Длительность импульса, 1 микросекунда
waveform.PRF = 1e3;             # Частота повторения импульсов, 1 кГц
waveform.SampleRate = 1e6;      # Частота дискретизации, 1 МГц

# Создание и настройка передатчика (1 и 2 этапы вместе, альтернативный вариант)
transmitter = EngeePhased.Transmitter(
    PeakPower = 50,                  # Пиковая мощность, 50 Вт
    Gain = 40,                        # Усиление, 40 дБ
);

# Создание и настройка приемника (1 и 2 этапы вместе, альтернативный вариант)
receiver = EngeePhased.ReceiverPreamp(
    SampleRate = 1e6,                # Частота дискретизации, 1 МГц
    NoiseFigure = 5,                 # Коэффициент шума, 5 дБ
    NoiseMethod = "Noise power",     # Способ задания шума, мощность
    NoisePower = 50000,              # Мощность шума
);

# Все предыдущие этапы формируют 3 пункт – сбор компонентов в систему, отражающую реальные физические процессы

# Запуск системы (4 этап)
signal = step!(waveform);               # Генерация очередного импульса
transmitted = transmitter(signal);      # Передача сигнала
received = receiver(transmitted);       # Прием сигнала с добавлением шумов

# (Опционально) Построение графиков сигналов
plot(abs.(signal), title="Переданный сигнал", label = false) |> display
plot(abs.(received), title="Принятый сигнал", label = false)

When system objects are called, data processing, initialisation and state management are performed, which simplifies the modelling of complex dynamic systems. In such systems, the output data depends not only on the current input values, but also on the previous state of the system. The system object stores this previous state to be used in the next computation step.

Stages of creating a system based on system objects

Working with system objects in Engee involves several basic steps that help organise the code into a logical structure representing physical processes. Let’s look at an example of creating a simple TFodeposition radar system to show how system objects are created and used.

Creating components

The first step is to create the basic objects that will represent the components of the system. Components are created by usage of the built-in Engee system classes representing various functional elements such as signal generators, transmitters and receivers.

To see all available parameters for configuring a component, create the component (execute the code) and in variable window variables article 2 1 hover the mouse over the corresponding component:

so param menu 1

An example of creating a rectangular pulse generator:

waveform = EngeePhased.RectangularWaveform()

Here EngeePhased.RectangularWaveform is a class representing a rectangular pulse generator. The waveform object will be the basis for generating the signals to be sent through the system. At this stage, only the object itself is created, without parameters so that it can be customised later. Alternatively, you can create and configure the component at the same time (see below for details).

Customising components

Once the components have been created, their parameters need to be set to match the requirements of the model. Customisation can be done in two ways: when the object is created or by changing properties after creation:

  1. Customising when creating a component:

    waveform = EngeePhased.RectangularWaveform(
    PulseWidth = 100e-6,
    PRF = 1e3,
    SampleRate = 1e6,
);

  2. Customisation via object properties after creation:

    waveform = EngeePhased.RectangularWaveform()

waveform.PulseWidth = 100e-6;
waveform.PRF = 1e3;
waveform.SampleRate = 1e6;

Here:

  • PulseWidth is the pulse width. Here it is set as 1 microsecond.

  • PRF - Pulse Repetition Frequency, which determines how often pulses are generated. It is set to 1 kHz.

  • SampleRate - Sampling Rate, which determines how fast the system processes data. It is set to 1 MHz.

The other components required to assemble the system are configured in a similar manner:

# Создание и настройка передатчика
transmitter = EngeePhased.Transmitter(
    PeakPower = 50,              # Пиковая мощность, 50 Вт
    Gain = 40                    # Усиление, 40 дБ
);

# Создание и настройка приемника
receiver = EngeePhased.ReceiverPreamp(
    SampleRate = 1e6,            # Частота дискретизации, 1 МГц
    NoiseFigure = 5,             # Коэффициент шума, 5 дБ
    NoiseMethod = "Noise power", # Способ задания шума, мощность
    NoisePower = 50000           # Мощность шума
);

Assembling components into a system

At this stage all the necessary components have been created and configured, but their interaction has not yet been defined. The system assembly consists of preparing objects that will represent elements of the real signal transmission and reception process, but the data flow between them is not yet organised.

In the above code, the system components are created and configured: signal generator, transmitter and receiver. These objects will be the basis for further modelling, but for now they remain isolated - the real interaction and data transfer between the components will be implemented at the next stage.

# Создание и настройка генератора сигнала
waveform = EngeePhased.RectangularWaveform()
waveform.PulseWidth = 100e-6    # Длительность импульса, 1 микросекунда
waveform.PRF = 1e3              # Частота повторения импульсов, 1 кГц
waveform.SampleRate = 1e6       # Частота дискретизации, 1 МГц

# Создание и настройка передатчика
transmitter = EngeePhased.Transmitter(
    PeakPower = 50,             # Пиковая мощность, 50 Вт
    Gain = 40                    # Усиление, 40 дБ
)

# Создание и настройка приемника
receiver = EngeePhased.ReceiverPreamp(
    SampleRate = 1e6,           # Частота дискретизации, 1 МГц
    NoiseFigure = 5,            # Коэффициент шума, 5 дБ
    NoiseMethod = "Noise power", # Способ задания шума, мощность
    NoisePower = 50000           # Мощность шума
)

Thus, at the assembly stage, all the components necessary to create a system that will process the signal are prepared.

Starting the system

Now that all the components have been created and configured, they can be combined into a system by organising the data transfer between them. In this step, the output of one component becomes the input of another, simulating the real process of signal transmission and reception:

signal = step!(waveform);
transmitted = transmitter(signal);
received = receiver(transmitted);

Description of the data transmission process:

  1. Signal generation - the waveform object generates a rectangular pulse;

  2. Signal transmission - the transmitter object amplifies the signal and transmits it. The parameters PeakPower sets the peak power of the transmitter and Gain sets the gain;

  3. Receive signal - the receiver object receives the signal and adds noise using the given parameters. NoiseFigure specifies the noise level, NoiseMethod indicates that the power-based noise addition method is used, and NoisePower specifies the noise power.

This step completes the system construction process and allows the modelling of signal transmission and reception to begin, taking into account noise and other characteristics.

Visualisation (optional step)

This optional stage allows you to visualise the results obtained after the system has been started. The stage helps to analyse the behaviour of the system and the quality of the received signal after passing through noise and amplification. In this example, graphs are plotted to evaluate the transmitted and received signals:

plot(abs.(signal), title="Переданный сигнал", label = false) |> display
plot(abs.(received), title="Принятый сигнал", label = false)

Here abs.(signal) and abs.(received) apply the abs function to each element of the array to get the amplitude of the signal. The plot function plots to visually compare how the signal has changed after passing through the transmitter and receiver.

so graph 1

so graph 2

Based on the graphs presented:

  • The upper graph shows a transmitted rectangular signal that starts with an amplitude of about 1 and drops rapidly to zero. This is a typical pulse-shaped signal corresponding to the rectangular wave parameters specified for the transmitter.

  • The lower graph shows the received signal, which contains a noise component. It can be seen that there is a noticeable level of amplitude at the beginning of the signal (up to about 250 samples) and then it decreases and becomes noisier. This is characteristic of a received signal where, due to the effects of noise and attenuation of the signal, its amplitude is reduced and the essential information becomes less pronounced.

The graphs demonstrate that the system based on system objects successfully perform their functions in modelling the radar signal. System objects allow to implement the main stages - generation, transmission, reception and noise addition - at the block level, without the need to dive into the details of modelling by means of Engee library blocks.

General methods of system objects

System objects in Engee offer a number of common methods that simplify the management and configuration of their behaviour. Each of these is described below.

step!

The step! method runs the basic logic or algorithm associated with a system object. It is used to perform calculations or data processing based on the current state of the object. For example, in a radar system, calling step! for a signal generator starts the process of generating the next pulse:

# Генерация импульса
signal = step!(waveform)

# Передача и прием сигнала
transmitted = step!(transmitter, signal)
received = step!(receiver, transmitted)

Here, the step! method sequentially starts each component: signal generator (waveform), transmitter (transmitter), and receiver (receiver), ensuring that the signal passes through the entire system. Each call to step! performs one iteration of data processing.

release!

After a system object has been configured and used, some of its properties may be locked. The release! method allows you to unlock the object and change its properties if you want to reconfigure its parameters. This method is useful when you need to make changes to an already configured object - for example, to change transmitter power or oscillator frequency - without creating a new object. Usage of release! frees the object to make new values to its parameters. For example:

release!(waveform) # Разрешаем изменения в объекте генератора сигнала

waveform.SampleRate = 2e6       # Изменение частоты дискретизации на 2 МГц

release!(transmitter) # Разрешаем изменения в объекте передатчика

transmitter.Gain = 45           # Изменение усиления на 45 дБ

In this example, the release! method allows you to make changes to existing waveform and transmitter objects without creating them again. This is useful if the parameters of the system need to be adapted to other operating conditions.

setup!

The setup! method performs the one-time actions required for the initial setup of a system object. It prepares the object for operation, e.g., checks the correctness of the specified parameters and allocates the necessary resources.

The setup! method is called automatically when step! is run for the first time, but it can be called manually to check the readiness of the object in advance and make sure that its settings are correct.

This method is useful for the model preparation stage, when it is important to make sure that all objects are correctly configured before the main processing begins. For example:

setup!(waveform)

By default, the setup! method cannot perform any changes to the waveform object (from the example above). To change the object’s characteristics, you must first call the release! method. Otherwise, the system will issue a warning:

so warning 1

Therefore, you must first unlock the object for changes and then call setup!:

release!(waveform)

setup!(waveform)

  1. Software control of simulation parameters