Concepts
This page explains what makes up a nonoha graph (workspaces, flows, graphs, nodes, and ports) and the data that flows between them. The examples use the template workspace you ran in Getting started.
Workspace
A workspace is one project that holds graphs, plugins, and the app's pages. The template workspace (templates/default) is laid out like this:
templates/default/
├── plugins/
│ ├── manifest.json the plugins to enable
│ └── user-nodes/ a Python package of nodes
└── flows/default.vnf/ the flow
├── flow.json the graphs to load
├── app/ the app's pages (served at /app)
└── graphs/app.vng/ a graph
├── graph.json nodes, properties, and edges
└── editors/nonoha-editor/models/settings.json the layout in the editorA workspace created in nonoha Hub also contains the engine (nonoha-engine/) and a pyproject.toml that declares the versions of the engine and its plugins.
Flows and graphs
A flow (.vnf) is a set of one or more graphs (.vng). flow.json lists the graphs, and the engine loads them in that order. The template's flow has one graph, app.
A graph can take another graph's outputs in the same flow with a GraphProxy node. List the graph that takes them after the graph it takes them from.
Nodes and ports
A node is a unit of processing with input ports, output ports, and properties. An edge connects an output port of one node to an input port of another. In graph.json, a port is written node name.port name (for example, Synthesizer_1.waveform).
A name that starts with . (such as .waveform) is an input or output port of the graph itself. The app's pages and other graphs work with a graph through these ports.
Properties are a node's settings, which you change from the editor or the API. A property that declares its data type is also a property port named with @ (such as Clock's @fs or Synthesizer's @frequency), so an edge can feed it values.
Port names can't contain ., -, or $, which are used as separators.
The data that flows
What flows through a port is a plain NumPy array (np.ndarray), not wrapped in a type of nonoha's own, so you can pass it straight to SciPy and other libraries. An array's shape and data type follow the port's type.
The first dimension of an array is the batch dimension: how many values it carries at once. The template's Clock (fs 600, pack_size 20) sends an array of 20 time values about every 33 milliseconds, and Synthesizer computes those 20 samples with array operations instead of a Python loop over samples. Sending values in batches means fewer calls, and less overhead per sample, than sending them one at a time.
Port types
A port's type is the data type and shape of one value. The arrays it carries have the batch dimension in front.
| Port type | One value | Shape of the arrays |
|---|---|---|
f32 | a 32-bit floating-point number | (batch,) |
f32[3] | a vector of length 3 | (batch, 3) |
f32[?] | a vector of any length | (batch, N) |
bool[6x8] | a 6×8 matrix of booleans | (batch, 6, 8) |
The data types are bool, i8 to i64, u8 to u64, f32, f64, c64, c128, str, and any, which takes anything.
An edge connects ports whose types match. A data type connects to the same type, or to one it converts to without losing precision (such as f32 to f64). Shapes match when they have the same number of dimensions and each dimension has the same length, or is ? on the receiving side. An input port of type any takes every type.
The engine, the editor, and apps
- nonoha engine: the server that runs a workspace's graphs. It has no GUI; it runs the computation. It provides a REST API and a WebSocket API, and serves the app's pages (
/app) and, when a build is present, the editor (/editor). - nonoha editor: an editor that runs in the browser. It connects to an engine, where you edit graphs as diagrams and watch them run.
- The app's pages: HTML and JavaScript in the workspace's
app/. They talk to the engine over WebSocket (Your own web UI). - nonoha embedded: a runtime that runs flows with the Python inside an app. You embed it in iOS and Android apps, where the app has its own screens and bundles the plugins. Nodes specific to the engine are not available there.
Using it safely
- The engine's API has no authentication. By default the engine accepts connections from your own machine (
127.0.0.1) only, but that alone does not make it safe. If you open it to a network with--host, use it only on networks you trust. - A graph can include nodes that run Python code, and plugins are Python packages that the engine loads and runs. Load graphs and plugins only from authors you trust.
nonoha-engine's SECURITY.md has the details.