Документация Engee

Работа с библиотеками Julia

Введение

Библиотеки Julia — это организованный набор готовых функций, классов и объектов для решения различных задач. Библиотеки Julia распространяются в виде пакетов, которые можно установить с помощью менеджера пакетов Pkg и использовать в своих проектах. При необходимости более четкого разделения библиотек на пользовательские и системные — используйте EngeePkg.

В Engee работа с библиотеками Julia также осуществляется через встроенной менеджер пакетов Pkg с помощью двух инструментов рабочего пространства — командную строку img 41 1 2 и редактор скриптов img41 1.

При работе с большим количеством библиотек удобно использовать редактор скриптов, в котором после вызова Pkg не требуется его повторная инициализация. Командная строка удобна в том случае, если вам привычнее работать с кодом вне интерфейса редактора скриптов и с небольшим количеством библиотек.

Подробное описание работы с менеджером пакетов Pkg можно найти здесь.

Принцип работы с библиотеками

  1. Найдите точное название интересующей вас библиотеки. Экосистема Julia содержит более десяти тысяч пакетов, зарегистрированных в общем реестре, что может сильно затруднить поиск нужного пакета. Для оптимизации поиска рекомендуем обратиться к следующим источникам:

    • Язык программирования в Engee — раздел Engee с полной документацией по Julia на русском языке.

    • JuliaHub — сервис для поиска по всей зарегистрированной документации пакетов с открытым исходным кодом с возможностью сортировки по тегам и ключевым словам.

    • Julia Packages — онлайн-ресурс, предназначенный для поиска, изучения и просмотра пакетов Julia с возможностью настройки фильтров по категориям, популярности и датам.

    • Julia.jl — главный репозиторий пакетов для языка программирования Julia. Этот репозиторий хранится на платформе GitHub и содержит множество полезных пакетов и инструментов, разработанных сообществом для работы с языком Julia.

  2. Выберите инструмент для работы с библиотеками — командная строка или редактор скриптов в зависимости от ваших задач.

  3. Инициализируйте работу с пакетами в Julia, добавив менеджер пакетов Pkg. Синтаксис добавления менеджера отличается в зависимости от выбранного инструмента.

  4. Добавьте библиотеки с помощью команды add в ваше окружение, чтобы использовать их в своем проекте. Синтаксис добавления библиотек зависит от выбранного инструмента.

  5. Загрузите библиотеку в пространство имен и получите доступ к ее конкретным элементам с помощью операторов using и import. Вы также можете добавить и собственные библиотеки.

  6. При необходимости узнайте статус библиотек через status, проверьте, какие библиотеки загружены в оперативную память Engee и удалите ненужные через remove или rm. Синтаксис зависит от выбранного инструмента.

Подробная информация о работе с библиотеками представлена ниже.

Библиотеки Julia в командной строке

Чтобы установить новую библиотеку в командной строке Engee, кликните левой кнопкой мыши в области ввода кода и нажмите закрывающую квадратную скобку ]. Это переключит командную строку на работу с менеджером пакетов. Строка изменит свой вид с engee> на pkg>:

pkg>

В режиме менеджера пакетов используем команду add для добавления библиотеки:

add Example

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

add Example, Plots, Pluto

Для удаления библиотеки используется команда remove или ее сокращенная версия rm:

remove Pluto
Вывод удаления библиотеки 
Updating `/user/.project/Project.toml`
  [c3e4b0f8] - Pluto v0.19.38
    Updating `/user/.project/Manifest.toml`
  [5218b696] - Configurations v0.17.6
  [e2d170a0] - DataValueInterfaces v1.0.0
  [21656369] - ExpressionExplorer v1.0.0
  [55351af7] - ExproniconLite v0.10.5
  [fb4132e2] - FuzzyCompletions v0.5.3
  [ac1192a8] - HypertextLiteral v0.9.5
  [82899510] - IteratorInterfaceExtensions v1.0.0
  [0e77f7df] - LazilyInitializedFields v1.2.2
  [6c6e2e6c] - MIMEs v0.1.4
  [36869731] - Malt v1.1.1
  [99f44e22] - MsgPack v1.2.0
  [c3e4b0f8] - Pluto v0.19.38
  [91cefc8d] - PrecompileSignatures v3.0.3
  [aea7be01] - PrecompileTools v1.2.0
  [2792f1a3] - RegistryInstances v0.1.0
  [3783bdb8] - TableTraits v1.0.1
  [bd369af6] - Tables v1.10.0
  [410a4b4d] - Tricks v0.1.6

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

remove Pluto, Plots, Example

Попытка удалить несуществующую библиотеку выдаст ошибку:

Вывод ошибки 
 The following package names could not be resolved:
* Имя библиотеки (not found in project or manifest)
Для выхода из режима менеджера пакетов pkg> кликните левой кнопкой мыши по области ввода кода и нажмите Backspace. Это вернет вас в первичный вид командной строки engee>.

Библиотеки Julia в редакторе скриптов

Чтобы установить новую библиотеку в интерактивном скрипте Engee, в секции с кодом импортируйте Pkg командой import Pkg, а затем выполните команду Pkg.add("Имя библиотеки"). Например, секция с кодом для добавления библиотеки Example будет выглядеть так:

import Pkg
Pkg.add("Example")

После нажатия кнопки Пуск img 1 1 2 на этой секции будет импортирован менеджер пакетов Pkg, и будет установлена библиотека Example. Информация о ходе установки библиотеки отобразится автоматически:

Resolving package versions...
Installed Example ─ v0.5.3
Updating `/user/start/Project.toml`
[7876af07] + Example v0.5.3
Updating `/user/start/Manifest.toml`
[7876af07] + Example v0.5.3

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

Pkg.add(["Example", "Plots"])

Для удаления библиотеки используется команда rm:

Pkg.rm("Example")

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

Pkg.rm(["Example", "Plots"])

Команда remove не определяется в редакторе скриптов, хотя и используется в командной строке. Попытка вызвать команду в редакторе выдаст ошибку:

`UndefVarError: `remove` not defined`
В редакторе скриптов имя менеджера пакетов Pkg и имена библиотек Julia чувствительны к регистру и должны начинаться с заглавной буквы, в противном случае вы получите сообщение об ошибке.

Статус библиотек

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

  1. Войдите в менеджер пакетов Pkg через ].

  2. Пропишите команду status:

pkg> status

После этого вы увидите список установленных библиотек и их версию:

Вывод статуса библиотек 
pkg> status
Status `/user/.project/Project.toml`
⌅ [c3fe647b] AbstractAlgebra v0.27.8
⌅ [7d9f7c33] Accessors v0.1.27
⌅ [79e6a3ab] Adapt v3.5.0
⌅ [91a5bcdd] Plots v1.36.1
⌃ [c3e4b0f8] Pluto v0.19.36

Символы ⌃ и ⌅ означают, что для библиотек есть новые версии:

  • ⌃ — имеется более новая версия.

  • ⌅ — имеется более новая версия, но есть конфликты по совместимости с другими библиотеками.

Узнать, какие библиотеки установлены и готовы использованию, можно и через редактор скриптов:

  1. Введите import Pkg, если не сделали этого ранее.

  2. Введите Pkg.status() для получения статуса библиотек.

Загрузка библиотек

В Julia для загрузки библиотек и предоставления доступа к их конкретным элементам, таким как функции, типы и переменные, используются операторы import и using:

  • using — используется для загрузки всех экспортированных имен из модуля и привязки их к текущему пространству имен. Например:

    using Statistics

x = mean([1, 2, 3, 4, 5])

  • import — используется для выборочного импорта определенных функций или переменных из модуля. Требует указания имени модуля перед именем функции или переменной. Следовательно, функция или переменная, не импортированные явно, не будут доступны в текущей среде. Пример:

    import Statistics

x = Statistics.mean([1, 2, 3, 4, 5])

Рассмотрим преимущества и ограничения операторов:

  • Преимущество using — удобство. Код становится более емким, все функции и переменные из модулей доступны в текущем пространстве имен.

  • Недостаток using — использование using для загрузки больших модулей со множеством функций и переменных может повлиять на производительность и переполнение памяти.

  • Недостаток using — конфликт имен. using может вызвать конфликты имен, если несколько модулей определяют функции или переменные с одинаковым именем.

  • Преимущество import — отсутствие конфликта имен.

  • Преимущество import — сокращение времени компиляции, избегая необходимости компилировать ненужный код.

  • Недостаток import — усложнение кода.

Таким образом, оператор using больше подходит для небольших проектов с упором на удобство. Оператор import больше подходит для крупных проектов с упором на избирательность и контролем над использованием памяти.

Создание собственных библиотек

Для добавления собственных библиотек используется команда module. Чтобы создать собственную библиотеку с помощью module в Julia, вам нужно выполнить следующее:

  1. Создадим скрипт module и назовем его так, как бы мы хотели назвать свою библиотеку, в нашем случае Test_lib и добавим содержимое модуля, например функцию:

    module Test_lib
    function get_value(x) # Функция возвращения значения
        return x
    end
end

  2. Для загрузки своей библиотеки используем оператор import или using (см. выше раздел загрузки библиотек):

    import.Test_lib

# или

using.Test_lib

  3. Далее получим требуемый параметр через оператор import:

    import.Test_lib.get_value
import_value = get_value(7) # Получим число 7

  4. Или через оператор using:

    using.Test_lib
using_value = get_value(7) # Получим число 7
Добавление точки между import и именем библиотеки обязательно в случае добавления собственной библиотеки из module. Аналогично и для using. Вы также можете добавить директорию с библиотекой в путь Engee, тогда ошибка не возникнет. В ином случае выведет ошибку:
Вывод ошибки 
ArgumentError: Package Test_lib not found in current path, maybe you meant `import/using .Test_lib`.
- Otherwise, run `import Pkg; Pkg.add("Test_lib")` to install the Test_lib package.

EngeePkg

Работа с EngeePkg

Используйте пакет EngeePkg для четкого разделения пользовательских и системных библиотек и для расширенного функционала работы с ними в вашем проекте.

EngeePkg — это надстройка над менеджером пакетов Pkg, реализованная как самостоятельный пакет для лучшего контроля над загруженными модулями и библиотеками.

EngeePkg обладает следующими преимуществами перед Pkg:

  • EngeePkg различает системные и пользовательские библиотеки, выделяя среди системных те, что входят в системный образ. По умолчанию функция EngeePkg.status выдает всю информацию из LOAD_PATH. Классический Pkg с функцией Pkg.status не обладает таким функционалом и выдает информацию о библиотеках только из одного проекта (по умолчанию — активного). Более того, EngeePkg.status, в отличие от Pkg.status, может выдавать информацию о загруженных модулях.

  • EngeePkg очищает весь пользовательский проект, удаляя все установленные библиотеки функцией EngeePkg.purge без явного перечисления. Классический Pkg очищает проект функцией Pkg.rm, но требует явного перечисления всех библиотек.

Для работы с EngeePkg добавьте его в текущее окружение (проект):

Pkg.add("EngeePkg")

Импортируйте EngeePkg в рабочее пространство (командная строка или редактор скриптов):

using EngeePkg

Обратитесь к справке в командной строке (используйте знак вопроса ? для переключения в режим help?) для вывода доступных команд EngeePkg:

ALL_MODULES         CLI                 INIT_MODULES        INSTALLED_MODULES
LOADED_MODULES      PKGMODE_MANIFEST    PKGMODE_PROJECT     PKGSORT_BY_NAME
PKGSORT_BY_SRCPATH  PKGSORT_BY_UUID     PKGSORT_NONE        PkgUtils
SYSTEM_MODULES      Status              USER_MODULES        eval
include             purge               select_packages     status

Далее рассмотрим функции EngeePkg.status и EngeePkg.purge на конкретных примерах.

Функция EngeePkg.status

Функция EngeePkg.status выводит статус установленных библиотек и/или загруженных модулей. EngeePkg.status, в отличие от Pkg.status, может выдавать информацию о загруженных модулях, различать системные и пользовательские библиотеки и определять, какие из системных библиотек входят в системный образ.

Сигнатура функции EngeePkg.status:

EngeePkg.status(modules::Union{String, UUID, Module, ModuleSelection};
                  mode::PackageMode, sort::PkgSortOrder, outdated::Bool, io::IO)

Опциональный первый аргумент modules задает выборку библиотек/модулей. Это может быть имя или UUID одной конкретной библиотеки, либо один модуль как таковой, либо константа, задающая множество библиотек/модулей:

  • USER_MODULES — установленные из пользовательских библиотек.

  • SYSTEM_MODULES — установленные из системных библиотек.

  • INSTALLED_MODULES — установленные во всех проектах (перечисляет пакеты из всех элементов LOAD_PATH).

  • LOADED_MODULES — загруженные в память (включая не установленные).

  • INIT_MODULES — загруженные в память из системного образа.

  • ALL_MODULES (по умолчанию) — все установленные и загруженные (перечисляет пакеты из всех элементов LOAD_PATH).

Аргумент io задает терминал для вывода (по умолчанию stdout).

Аргумент sort задает порядок перечисления:

  • PKGSORT_BY_NAME — сортировать по именам пакетов;

  • PKGSORT_BY_SRCPATH — сортировать по расположению исходных файлов установленных пакетов;

  • PKGSORT_BY_UUID — сортировать по UUID пакетов;

  • PKGSORT_NONE (по умолчанию) — без сортировки.

Аргумент mode задает режим выборки установленных библиотек:

  • PKGMODE_PROJECT — по файлу проекта (Project.toml);

  • PKGMODE_MANIFEST — по файлу манифеста (Manifest.toml).

При выборке только установленных пакетов (USER_MODULES, SYSTEM_MODULES, INSTALLED_MODULES) по умолчанию используется файл, содержащий данные о прямых зависимостях проекта (Project.toml). При выборке загруженных (LOADED_MODULES, INIT_MODULES, ALL_MODULES), а также при выборке по имени и UUID — файл, описывающий структуру данных проекта (Manifest.toml).

Вывод использует тот же формат, что и Pkg.status. При выборке библиотек из нескольких проектов для их различения используются значки ①, ② и т.д. Значком ▣ отмечаются загруженные пакеты. Например:

Status ① `/user/.project/Manifest.toml`
             ② `/usr/local/julia-1.9.3/environments/v1.9/Manifest.toml`
 ⌅ [39de3d68] AxisArrays v0.4.6 ② ▣
 ⌅ [98e50ef6] JuliaFormatter v1.0.20 ② ▣
   [2aef5ad7] QueryOperators v0.9.3 ②
 ⌅ [48965c70] MatrixPencils v1.7.5 ② ▣
 ⌃ [69666777] Arrow v2.4.3 ②
   [49dc2e85] Calculus v0.5.1 ② ▣
   [efcefdf7] PCRE2_jll v10.42.0+0 ② ▣
 ⌅ [d8a4904e] MutableArithmetics v1.1.0 ② ▣
 ⌅ [aacddb02] JpegTurbo_jll v2.1.91+0 ② ▣

Функция Pkg.status менеджера пакетов Pkg может выдавать информацию о пакетах только из одного проекта (по умолчанию — активного). Например:

Status `/user/.project/Project.toml`
  [e36ba207] EngeePkg v0.0.7
  [4d00f742] GeometryTypes v0.8.5
⌅ [23fbe1c1] Latexify v0.15.18

К функции EngeePkg.status примыкает EngeePkg.select_packages. Если status печатает информацию в человеко-читаемом виде, то select_packages возвращает ту же информацию в виде объекта данных, с которым можно работать программно.

Сигнатура функции select_packages:

EngeePkg.select_packages(modules::Union{String, UUID, Module, ModuleSelection},
                           mode::PackageMode)

Функция select_packages получает выборку установленных пакетов и/или загруженных модулей в виде массива описаний пакетов. Аргументы modules и mode имеют тот же смысл, что в EngeePkg.status.

Функция EngeePkg.purge

Функция purge удаляет все библиотеки, установленные в заданном окружении (по умолчанию — в пользовательском проекте):

EngeePkg.purge()
Вывод исполнения команды 
Updating `/user/.project/Project.toml` #удаление библиотек из Project.toml (пользовательские)
  [c3fe647b] - AbstractAlgebra v0.27.8
  [7d9f7c33] - Accessors v0.1.27
  [79e6a3ab] - Adapt v3.5.0
  [e36ba207] - EngeePkg v0.0.7
  [cd3eb016] - HTTP v1.5.4
  ...
  [91a5bcdd] - Plots v1.36.1
  [c3e4b0f8] - Pluto v0.19.40
  [438e738f] - PyCall v1.94.1
  [d330b81b] - PyPlot v2.11.2
  [3646fa90] - ScikitLearn v0.7.0
  [6a2ea274] - Torch v0.1.0
    Updating `/user/.project/Manifest.toml` ##удаление библиотек из Manifest.toml (системные)
  [c3fe647b] - AbstractAlgebra v0.27.8
  [7d9f7c33] - Accessors v0.1.27
  [79e6a3ab] - Adapt v3.5.0
  [b99e7846] - BinaryProvider v0.5.10
  [d1d4a3ce] - BitFlags v0.1.7
  ...
  [d360d2e6] - ChainRulesCore v1.15.7
  [944b1d66] - CodecZlib v0.7.1
  [19ecbf4d] - Codecs v0.5.0
  [35d6a980] - ColorSchemes v3.20.0
  [3da002f7] - ColorTypes v0.11.4

Функция используется для полной очистки пользовательского проекта. Менеджер пакетов Pkg не поддерживает такой функционал — доступна функция Pkg.rm, для которой доступно только явное перечисление всех библиотек.

Среды Julia в Engee

expirienced users 1

Операторы import и using различаются контекстом кода и загружаемыми файлами в зависимости от текущей среды. В Julia есть два типа сред:

  • Среда проекта (project environment) — это набор файлов и настроек, определяющих окружение для разработки и выполнения конкретного проекта. Среда проекта включает в себя настройки и зависимости, которые используются в проекте. В Julia среда проекта определяется с помощью файлов Project.toml и Manifest.toml, которые содержат информацию о зависимостях и их версиях:

    • Файл проекта (Project.toml) — это файл, содержащий информацию о прямых зависимостях проекта. Он определяет имена и идентификаторы (например, имена библиотек), которые используются в проекте. Этот файл обычно содержит только прямые зависимости и их версии.

    • Файл манифеста (Manifest.toml) — это файл (если он существует), описывающий полный граф (структуру данных) зависимостей проекта. Включаются не только прямые зависимости, но и все косвенные зависимости, которые используются в проекте. Для каждой зависимости указываются точные версии (например, библиотек) и другие сведения, необходимые для обеспечения совместимости исходного кода проекта с версиями его зависимостей.

  • Каталог проекта (project directory) — это место, где содержатся файлы и структура вашего проекта, включая исходный код, настройки, конфигурационные файлы и наборы библиотек. Среда проекта формируется естественным образом из структуры файлов и каталогов внутри каталога проекта. В каталоге содержатся библиотеки и модули, организованные в иерархию подкаталогов. Если внутри каталога библиотеки есть файл имя_библиотеки.jl в подкаталоге src — это означает, что библиотека имя_библиотеки доступна в этом проекте, и ее код загружается через этот файл.

Таким образом, среда проекта — это абстрактная среда, в которой находятся зависимости проекта, в то время как каталог проекта — это место, где физически хранятся файлы проекта. Подробнее читайте здесь.

Среда Julia определяет, какие пакеты и зависимости должны быть доступны для конкретного проекта или приложения. Затем LOAD_PATH в виде массива пути используется, чтобы указать Julia, где именно искать пакеты и модули связанные с этой средой:

  • LOAD_PATH[1] — первый элемент массива пути, задающий путь к файлам пользовательского окружения. В пользовательских Manifest.toml и Project.toml файлах указывается, какие пакеты и какие версии необходимы для данного проекта. LOAD_PATH сам по себе не изменяется ни при добавлении пакетов (Pkg.add), ни при изменении toml-файлов окружения. По умолчанию пользовательское окружение создается по пути /user/.project. Это позволяет Julia находить и загружать пакеты, необходимые для выполнения кода в данном проекте.

  • LOAD_PATH[2] — второй элемент массива пути, задающий путь к файлам системного окружения. LOAD_PATH[2] указывает путь к системным пакетам, которые доступны для всех проектов и независимы от конкретного проекта. Путь к глобальным toml-файлам, таким как Manifest.toml и Project.toml не включается в элемент LOAD_PATH[2]. Вместо этого указывается путь к директории, содержащей эти файлы. Следовательно, пакеты, установленные системно, могут быть доступны из любого проекта, независимо от того, какие пакеты указаны в его собственных файлах проекта и манифеста. По умолчанию системное окружение создается по пути /user/local/julia-1.M.N/environments/v1.M/, где M и N — версия Julia в текущем проекте.

LOAD_PATH может содержать не только два элемента массива пути, но и любое количество путей к каталогам, в которых находятся пакеты. Когда Julia ищет пакет для загрузки с помощью using или import, она проверяет все пути, указанные в LOAD_PATH.

Помимо LOAD_PATH существует и подмножeство пакетов loaded_modules. loaded_modules (загруженные модули) относятся к списку модулей (или пакетов), которые в данный момент времени активны в текущем сеансе Julia. Каждый модуль представляет собой набор функций и данных, которые были загружены и готовы к использованию в коде.

Таким образом, Julia может загружать и использовать необходимые пакеты из всех окружений, пути к которым указаны в элементах массива LOAD_PATH. Функция Base.loaded_modules возвращает список загруженных модулей. Для лучшего восприятия представлен рисунок ниже:

julia libs 1

Следовательно, Julia может загружать и использовать пакеты, необходимые для проекта, используя пути, указанные в элементах массивов пути LOAD_PATH[1] и LOAD_PATH[2]. Тогда использование using и import:

  • using — используйте using если необходимо загрузить модуль и сделать все его экспортированные символы доступными в текущем пространстве имен. using загружает модуль в память и добавляет его в список загруженных модулей (loaded_modules), что означает, что его функции и переменные становятся доступными напрямую в коде. Это удобно, когда вам нужно часто использовать функции или переменные из модуля без необходимости повторного указания его имени.

  • import — используйте import если необходимо загрузить модуль, но нет нужны в импорте всех его символов в текущее пространство имен. import не загружает модуль в память и не добавляет его в loaded_modules, но создает ссылку, позволяя использовать символы через квалифицированные имена. Используйте import, если нужны только определенные символы из модуля или нужно явно указать их происхождение, чтобы избежать конфликтов имен.

Таким образом, основное различие заключается в том, что using загружает и импортирует все экспортированные символы модуля, в то время как import создает ссылку на модуль, позволяя выбирать, какие символы использовать.

Полезные ссылки

  1. Работа с Pkg в Julia

  2. Модули в Julia

  3. Справка по API в Julia

  4. Командная строка

  5. Редактор скриптов