CMLabs · Psyclone AIOS

# 1. Introduction

Psyclone is a platform for building large-scale modular applications and for integrating disparate software and hardware into one coherent, live-monitorable system. This chapter explains what Psyclone is, why it exists, what it is good at, and what you need before you start.

## What is Psyclone?

The full name is Psyclone AIOS — “AI Operating System”: not an OS you install on hardware, but the runtime that hosts, connects and monitors the parts of your application, the way an operating system hosts processes. A Psyclone system is a collection of components — from a handful to thousands — that communicate by messages and signals in a context-sensitive publish/subscribe (PubSub) environment. Components can run on a single computer or be spread across a heterogeneous grid of machines running different operating systems. The whole system is described in a single XML file, the PsySpec, and monitored live through the built-in PsyProbe web interface.

The three component kinds are:

Component | What it does | Chapter
--- | --- | ---
Module | Subscribes to input messages via triggers (a declaration of which message types wake it), processes them in one or more crank functions (the piece of C++ or Python code that does the work), and publishes results through posts (a declaration of which message type each output gets). Can be a few lines or hundreds, multi-threaded, or embedded in another application. | 4
Whiteboard | A message store: it keeps posted messages and offers a sophisticated retrieval query language, plus visual message viewing and filtering in PsyProbe. (Under the hood it is a specialised catalog.) | 7
Catalog | An advanced module that additionally answers synchronous queries: data stores with a simple query language, or conduits to other systems (search services, recognition servers, other robots…). | 8

A few more words you will meet constantly: messages carry a dot-notation type (a PsyType, e.g. `input.video.raw`) that subscriptions match against; each running Psyclone instance is a node, and within a node components can be grouped into spaces (separate OS processes, for crash isolation). All of these — and the rest of the vocabulary — are collected in the Glossary.

Modules subscribe to input by message type, and subscriptions can change dynamically per context or be rewritten at runtime. Components are distributed across computers manually or automatically, and can migrate at runtime for load balancing. Process separation means a crashing module can be restarted without harming the rest of the system — you can safely mix commercial-grade and experimental code in one application.

## Psyclone at a glance

A Psyclone system: modules post and receive typed messages through the publish/subscribe bus; whiteboards store messages; catalogs answer queries. All of it is declared in one PsySpec file and observable live in PsyProbe.

## Why Psyclone? The USPs

- A unique publish/subscribe model. The entire system — components and dataflow — is set up from a single start-up configuration file, yet components and dataflow can be added, changed and removed dynamically at runtime.
- Multi-OS, multi-language. One system can span Windows and UNIX machines and mix modules written in C++ and Python (Java support is on the roadmap) Roadmap.
- Near real-time rerouting. Dataflow between components can be rerouted on the fly in response to context changes, incoming data, or resource availability.
- Dynamic algorithm switching. Swap the algorithm processing a data stream at runtime — for example downgrading to a cheaper algorithm under load.
- Web-based monitoring and operation. PsyProbe gives operators and developers a live view of the whole system, with support for custom visualisation plug-ins.

## What is Psyclone good at?

Psyclone is production-ready, includes built-in load balancing, and supports incremental development: start with skeleton modules and flesh them out over time while the system keeps running. Built-in components can record part or all of the dataflow of a live system and play it back offline for analysis and repeatable testing (see Replay Catalog). Typical application patterns:

### Grid-based live data analysis

A processing pipeline with branching, spread across a grid of machines. Global contexts adjust the flow at runtime; under load the system can automatically downgrade to cheaper algorithms. Nodes can be added and removed while the system runs, and components moved between them for manual or automatic load balancing — an alternative to batch frameworks when you need live analysis.

### Agent-based simulation

Hundreds of modules across multiple computers, defined in one configuration file and monitored in PsyProbe. A global time-step signal acts as the conductor's stick; each simulated entity is typically a group of ~10 modules sharing identical cranks but variable or randomised initial parameter values. Custom PsyProbe visualisers show the simulation state live.

### Interactive robots

The CoCoMaps project (EU Echord++) ran one Psyclone system per robot — partly onboard, partly on a server over WiFi — on top of ROS: multi-camera vision, face and emotion recognition, speech recognition and generation, dialogue and task planning, and navigation. Multiple Psyclone systems negotiated observations, roles and tasks through a shared external CCM Catalog (Collaborative Cognitive Maps). See the System Guide chapter on advanced applications for the full case study.

### Integrating third-party applications

Use Psyclone as the glue between otherwise incompatible applications: external components connect over the network with minimal latency, DataMessages carry any payload including binary blobs and nested messages with microsecond-synchronised timestamps across computers, and PsyProbe monitors the whole exchange in real time without interfering.

Tip. If you just want to see Psyclone run, skip ahead to the Quick Start — the ping-pong example runs in under a minute.

## Licensing

Psyclone is dual-licensed:

- LGPL open source — free for both academic and commercial use.
- Commercial licence — adds support and priority change requests.

Psyclone includes the CMSDK base library, which is licensed under an extended BSD licence. Both licences add the CADIA Clause, a limited-use condition: the software may not be used for (i) intentionally causing bodily injury or severe emotional harm, (ii) invading privacy or violating human rights, or (iii) committing or preparing acts of war.

## Supported platforms & languages

Area | Supported
--- | ---
Windows | Windows 7 or later; builds with Visual Studio (2015 or later)
UNIX / Linux | Recent Linux and X86 UNIX systems; GCC 5+, GLIBC 2+
macOS | Roadmap — not currently supported
Languages | C++ and Python for module code; Java support Roadmap

Note. The toolchain versions above reflect the original reference manual's minimums; newer compiler and Python versions are generally what you will use today. Python 2 is end-of-life — treat Python 2 crank support as legacy and prefer Python 3 (see Modules).

## Prerequisites

Psyclone deliberately has almost no dependencies:

- No third-party libraries are required beyond the bundled CMSDK.
- Windows: standard Visual Studio runtime libraries, dynamically linked.
- Linux: the system libraries `pthread`, `dl` and `rt`.
- Optional: OpenSSL development libraries if you build the SSL-enabled variant, and Python development headers/libraries if you build Python module support (details in Quick Start).

## How this guide is organised

Chapters 2–3 get you running and teach the mental model. Chapters 4–9 cover building systems: modules, messaging, contexts, whiteboards, catalogs and data messages. Chapters 10–12 cover scaling out and monitoring. Chapter 13 is the complete PsySpec XML reference with honest per-feature status badges, and chapter 14 collects step-by-step tutorials. System administration topics (logging, security/SSL, PsyProbe configuration, distributed administration) live in the companion System Guide.

PreviousOverview NextQuick Start