Обзор конструкций декларативного языка Engee

Страница в процессе разработки.

В декларативном языке физического моделирования Engee каждая часть физического компонента оформляется через отдельные конструкции. Они задают параметры, переменные, уравнения, порты, ветви, аннотации и многое другое. Ниже приведен обзор всех доступных конструкций:

Конструкция Назначение Пример

Конструкция	Назначение	Пример
`@parameters`	Параметры компонента, задаваемые перед запуском.	`@parameters begin R = 1.0, [unit = "Ohm"] end`
`@variables`	Переменные состояния, вычисляемые во время моделирования.	`@variables begin v = 0.0, [unit = "V"] end`
`@equations`	Уравнения, описывающие поведение.	`@equations begin v ~ R * i end`
`@nodes`	Порты подключения к физическим доменам.	`@nodes begin p = EngeePhysicalFoundation.Electrical.Pin end`
`@branches`	Связывает потоки нескольких портов в общую переменную.	`@branches begin i:(p.i, n.i) end`
`@intermediates`	Промежуточные выражения, упрощающие уравнения.	`@intermediates begin power = v*i end`
`@components`	Подкомпоненты внутри модели (иерархия).	`@components begin cap = Capacitor() end`
`@extend`	Наследование от существующего компонента.	`@engeemodel MyResistor begin @extend Resistor end`
`@inputs`, `@outputs`	Входные и выходные сигналы (нефизические коннекторы).	`@inputs begin u end @outputs begin y end`
`@structural_parameters`	Параметры, влияющие на структуру модели.	`@structural_parameters begin N = 3 end`
`@defaults`	Значения по умолчанию для параметров и переменных.	`@defaults begin T = 300.0 end`
`@annotations`	Служебные данные: описание, единицы, группы, приоритеты.	`@annotations begin description = "Thermal element" end`
`@icon`	Внешний вид иконки блока.	`@icon begin rectangle("Resistor") end`
`@modecharts`	Дискретные режимы работы (гибридная динамика).	`@modecharts begin mode Normal mode Overheated end`
`@events`	События, изменяющие состояние при выполнении условия.	`@events begin when v > 100.0 => i = 0.0 end`

@parameters

Параметры компонента, задаваемые перед запуском.

@parameters begin
    R = 1.0, [unit = "Ohm"]
end

@variables

Переменные состояния, вычисляемые во время моделирования.

@variables begin
    v = 0.0, [unit = "V"]
end

@equations

Уравнения, описывающие поведение.

@equations begin
    v ~ R * i
end

@nodes

Порты подключения к физическим доменам.

@nodes begin
    p = EngeePhysicalFoundation.Electrical.Pin
end

@branches

Связывает потоки нескольких портов в общую переменную.

@branches begin
    i:(p.i, n.i)
end

@intermediates

Промежуточные выражения, упрощающие уравнения.

@intermediates begin
    power = v*i
end

@components

Подкомпоненты внутри модели (иерархия).

@components begin
    cap = Capacitor()
end

@extend

Наследование от существующего компонента.

@engeemodel MyResistor begin
    @extend Resistor
end

@inputs, @outputs

Входные и выходные сигналы (нефизические коннекторы).

@inputs begin
    u
end
@outputs begin
    y
end

@structural_parameters

Параметры, влияющие на структуру модели.

@structural_parameters begin
    N = 3
end

@defaults

Значения по умолчанию для параметров и переменных.

@defaults begin
    T = 300.0
end

@annotations

Служебные данные: описание, единицы, группы, приоритеты.

@annotations begin
    description = "Thermal element"
end

@icon

Внешний вид иконки блока.

@icon begin
    rectangle("Resistor")
end

@modecharts

Дискретные режимы работы (гибридная динамика).

@modecharts begin
    mode Normal
    mode Overheated
end

@events

События, изменяющие состояние при выполнении условия.

@events begin
    when v > 100.0 => i = 0.0
end

Правила работы конструкций

Все конструкции оформляются в виде @имя begin … end.
Порядок следования конструкций внутри физического компонента (в коде после @engeemodel) не имеет значения — язык декларативный.

Например, переменную можно использовать в уравнении еще до ее явного объявления:
```
@engeemodel Example begin
    @equations begin
        y ~ x^2 + 1   # используем x, хотя он объявлен ниже
    end
    @variables begin
        x = 0
        y = 0
    end
end
```
Внутри уравнений и выражений можно ссылаться на параметры и переменные, объявленные выше или ниже по тексту.
В одном физическом компоненте может быть несколько конструкций одного типа (например, несколько блоков @equations).
Конструкции можно снабжать метаданными (например, group = "Parameters"), которые управляют отображением и поведением (см. ниже).
Проверки условий (assert) обычно размещаются в блоке @equations.

Использование `default()`

Для получения числового значения параметров и переменных (в системе СИ) применяется функция default(). Это нужно при передаче значений в подкомпоненты, условиях или вызове функций на Julia.

@parameters begin
    smoothing_factor = 0
end
@variables begin
    x = 0
end
@equations begin
    a = if default(smoothing_factor) == 0
        x
    else
        x / default(smoothing_factor)
    end
end

Несколько переменных в одной конструкции

В одной конструкции можно объявить несколько параметров или переменных сразу, если у них одинаковые метаданные.

@intermediates [access = Private] begin
    a, b = [3, 5]
    c, d = f(x)
end

Типизация

Для параметров и переменных можно указывать типы данных: скаляр, вектор, матрица, булево значение, перечисление.

@parameters begin
    a::Bool = true
    b = 1
    c[:] = [2, 3]         # вектор
    d[:, :] = [1 2; 3 4]  # матрица
end

Типизация влияет на то, как параметр отображается в интерфейсе (например, Bool превращается в чекбокс). Подробнее про типизацию в декларативном языке Engee читайте в статье Типизация и единицы измерения декларативного языка Engee.

Метаданные

Метаданные позволяют задавать дополнительные свойства параметров, переменных, узлов и других конструкций. Они не влияют на уравнения напрямую, но определяют единицы измерения, отображение в интерфейсе, группировку и другие аспекты.

Метаданные записываются в квадратных скобках после объявления и помогают сделать модель понятной и удобной для работы. Пример использования:

@parameters [group = "Parameters"] begin
    R = 1.0, [unit = "Ohm", description = "Resistance"]
end

В этом примере параметр R снабжен метаданными:

unit = "Ohm" — единица измерения;
description = "Resistance" — описание;
group = "Parameters" — группировка в окне настроек.

Часто используемые поля метаданных:

unit — единицы измерения (например, "Ohm", "V", "A").
description — текстовое описание.
group — группировка для интерфейса.
priority — приоритет отображения.
gui — управление видимостью в редакторе.
access — уровень доступа (публичный или внутренний).
view — отображение в GUI.
inside — внутреннее использование.

Подробнее о всех доступных метаданных, их назначении и примерах см. в статье: Метаданные декларативного языка Engee.

Прочие конструкции

В дополнение к основным конструкциям существуют те, которые используются реже, но играют важную роль в моделировании:

assert(…) — функция проверки условий. Обычно размещается в @equations. Проверка может выполняться на этапе компиляции или во время моделирования — это зависит от того, какие переменные участвуют в выражении. Пример:
```
@equations begin
    assert(R >= 0.0)
end
```
@initialequations — уравнения, действующие только в начальный момент времени. Используются для задания начальных условий, когда их нельзя выразить простыми целевыми значениями переменных. Пример:
```
@initialequations begin
    v = 0.0
end
```
@functions — объявление пользовательских функций. Функции можно определять внутри компонента и затем использовать в уравнениях. Пример:
```
@functions begin
    f(x) = x^2 + 1
end
```
connect(…) — соединение портов разных компонентов в схеме. Создает уравнения равенства потенциалов и баланса потоков. Пример:
```
connect(R1.p, R2.n)
```
domain_connect(…) — выравнивание параметров среды между портами одного компонента. Не соединяет переменные, а только синхронизирует параметры домена (например, температуру, минимальную проводимость). Пример:
```
domain_connect(n, p)
```