Using sygnm

From sygnm
Jump to: navigation, search

The sygnm framework can be used in multiple ways depending on the intention of the user. There are interactive clients for relatively simple calculations (currently command line and Jupyter Notebook). These are similar to traditional computer algebra systems, but by design aren't suitable for writing large and complex software. For more complex problems and longer programs, the sygnm API can be used from Python or from C++. There are also bots for some internet services (currently IRC and Discord). Finally, it is also possible to run the sygnm core as a standalone process and controlling it from some other process which is useful for writing user interfaces or other clients (see the developer manual for more information).

Overview of sygnm components

The following table gives an overview of the main components of the sygnm framework. See below for detailed descriptions.

Component name

Executable name

Description

sygnm-cli

sygnm-cli

Command line interface for interactive use.

sygnm-jupyter

N/A (used from within Jupyter Notebook)

Jupyter notebook kernel for sygnm interactive mode.

sygnm-irc

sygnm-irc

IRC client.

sygnm-discord

sygnm-discord

Discord bot.

sygnm-core

sygnm

sygnm as a standalone process, using an I/O interface specified in the configuration. Not intended for direct use, designed to be controlled from another process (e.g. a graphical user interface). sygnm-core also contains all APIs (C++ and Python) and packages.

sygnm examples

TODO

Code examples of sygnm packages and the C++ and Python APIs. Intended for developers.

sygnm code generator

sygnm-codegen

Code generator for (package) developers.

General configuration and paths

sygnm usually reads its configuration from a configuration file. In some clients, this can be specified as a command line argument (--core.config_file <filename>) and further configurations can be passed as command line arguments. When used as a library, the configuration must be passed as an argument to the initialization function.

In some clients, if there is no user-specified configuration file given, sygnm tries to read its configuration from the user configuration path, or if there is no such configuration file, tries to create it based on the default configuration (if available). However, this behavior must be enabled explicitly when sygnm is used as a library. For more information, see the list of configuration options.

sygnm searches for the default configuration template in the data path. Packages are loaded from the package paths read from the configuration file.

Overview of sygnm paths:

Path name

Description

Value

Write access needed

User configuration path

User-specific configuration files

Usually read from an environment variable or a platform-specific hard-coded value is used, see Configuration for details.

Yes

Data path

Global (non-package) data, configuration templates and other files

Read from the environment in the following order (first valid one is used): SYGNM_DATA_PATH environment variable, a platform-specific value determined by the build system at compilation time (${CMAKE_INSTALL_PREFIX}/share), a list of platform-specific values hardcoded in the sygnm platform implementation (on Linux, these are /usr/share/ and /usr/local/share/).

No

Package paths

Package files and data

Read from the configuration. Can be overridden with the SYGNM_PACKAGE_PATHS environment variable. The default value is platform-specific, determined by the build system at compilation time (${CMAKE_INSTALL_PREFIX}/lib).

No

All paths must be valid for correct operation. The used paths are written to the log at startup. If sygnm was built and installed correctly, no manual configuration of paths is necessary and the user configuration is created automatically at the first start as described above.

Interactive clients

sygnm-cli

sygnm-cli is a simple command line interface. When started, it will try to read (or if not found, create) the user-specific sygnm configuration file. The used parser and renderer can be specified in the configuration file or as command line options (see Configuration).

sygnm-jupyter

sygnm-jupyter consists of Jupyter Notebook kernels (JSON files) and a Python module (the implementation of the kernels). For installing the Jupyter Notebook kernels, refer to Jupyter Notebook documentation.

The kernels will run sygnm-core as a standalone process. Currently, the Python module is hardcoded to start sygnm without any command line parameters, so it is necessary that sygnm is correctly installed before the Jupyter Notebook interface can be used (the user-specific sygnm configuration will be used, or if it doesn't exist created from the default template).

Language APIs

C++ API

The sygnm-core headers are in the sygnm directory (i.e. use #include <sygnm/utils.h>-style includes in your code). The <sygnm/sygnm.h> convenience header can be used to include all of sygnm-core in a single include statement. The package headers are in the sygnm/packages/package_name directories.

See the code examples for more information.

Python API

Import the sygnm.sygnm module for the sygnm-core API. Import sygnm.packages.package_name for the package APIs.

See the code examples for more information.

Internet services

IRC bot

sygnm-irc is a simple IRC bot. When started, it will try to read (or if not found, create) the user-specific sygnm configuration file. The used parser, renderer, username (nick), channel, server address and port can be specified in the configuration file or as command line options (see Configuration). sygnm-irc can only connect to a single channel on a single server.

Discord bot

sygnm-discord is implemented in Python and requires discord.py. It runs sygnm-core as a standalone process. Currently, sygnm-discord is hardcoded to start sygnm without any command line parameters, so it is necessary that sygnm is correctly installed before sygnm-discord can be used (the user-specific sygnm configuration will be used, or if it doesn't exist created from the default template). The user must first register a bot on Discord and acquire a bot token (see the Discord documentation for more details), then add this bot token to the sygnm configuration file (see Configuration).

sygnm-core as a standalone process

When started as a standalone process, sygnm will try to read the user-specific sygnm configuration (or create it if it doesn't exist). After initialization, the I/O interface specified in the configuration will be started. In addition to the configuration file, arbitrary configuration options can be passed as command line arguments.