# Nallely MIDI Experimental Virtual Devices: How to Enable and Use Them

> Discover Nallely MIDI experimental virtual devices. Learn how to enable them using the CLI flag or Python API for advanced MIDI control.

- Repository: [dr-schlange/nallely-midi](https://github.com/dr-schlange/nallely-midi)
- Tags: how-to-guide
- Published: 2026-02-28

---

**Enable nallely's experimental virtual devices by passing the `--experimental` flag to the CLI or setting `include_experimental=True` in the Python API, which imports all `VirtualDevice` subclasses from the `nallely.experimental` package.**

The nallely-midi framework ships with a collection of experimental virtual devices that extend its modular synthesis capabilities beyond the default built-in MIDI devices. These advanced components—including chaotic generators, fractal renderers, and specialized routers—live in the `nallely.experimental` package and require explicit activation to load. Understanding how to enable these experimental virtual devices unlocks generative music workflows using mathematical attractors and non-standard signal processors.

## What Are Experimental Virtual Devices?

Experimental virtual devices in nallely are specialized subclasses of `VirtualDevice` that reside in the `nallely.experimental` package. Unlike the core built-in devices (such as Korg Minilogue or NTS-1 implementations), these components are not loaded by default to maintain stability and predictable resource usage.

When activated via the `--experimental` flag or `include_experimental=True` parameter, the framework performs a dynamic import of all classes in the experimental package. This occurs in [`nallely/trevor/trevor_bus.py`](https://github.com/dr-schlange/nallely-midi/blob/main/nallely/trevor/trevor_bus.py) at lines 828-831, where the boolean flag triggers an `import *` operation that registers every discovered `VirtualDevice` subclass with the device registry.

## Available Experimental Virtual Devices

The `nallely/experimental` directory contains four primary categories of devices, each serving distinct synthesis and routing functions.

### Routers

The routing layer provides specialized memory and distribution devices:

- **BroadcastRAM8** ([`nallely/experimental/routers.py`](https://github.com/dr-schlange/nallely-midi/blob/main/nallely/experimental/routers.py)): An 8-slot RAM buffer that broadcasts written values immediately to all connected outputs, useful for synchronized parameter distribution across multiple downstream devices.

### Random Patchers

These devices enable generative patching and randomization workflows:

- **InstanceCreator** ([`nallely/experimental/random_patchers.py`](https://github.com/dr-schlange/nallely-midi/blob/main/nallely/experimental/random_patchers.py)): Dynamically instantiates a random number of other virtual devices at runtime, creating emergent patch configurations.
- **RandomPatcher** ([`nallely/experimental/random_patchers.py`](https://github.com/dr-schlange/nallely-midi/blob/main/nallely/experimental/random_patchers.py)): Automatically establishes random parameter connections between existing devices in the current session, generating unpredictable modulation routings.

### Maths: Chaotic and Fractal Generators

The mathematics module ([`nallely/experimental/maths.py`](https://github.com/dr-schlange/nallely-midi/blob/main/nallely/experimental/maths.py)) contains the largest collection of experimental devices, implementing strange attractors and fractal algorithms as signal generators:

**Chaotic Attractors:**
- **HenonProjector**: Implements the Hénon map, a two-dimensional discrete-time dynamical system producing chaotic sequences.
- **LorenzProjector**: Simulates the Lorenz attractor with normalized X/Y/Z axes output, translating meteorological chaos theory into modulation sources.
- **RosslerProjector**: Generates signals from the Rössler attractor, known for its simpler chaotic behavior compared to the Lorenz system.
- **LorenzAttractor**: An alternative implementation of the Lorenz system with different parameter defaults for varied chaotic characteristics.

**Fractal Renderers:**
- **BarnsleyProjector**: Iterates the Barnsley fern fractal algorithm, outputting coordinate values suitable for panning or timbre modulation.
- **BuddhabrotProjector**: Performs high-resolution trajectory tracing for Buddhabrot rendering, outputting density values from Mandelbrot set orbits.
- **MandelbrotProjector**: Classic Mandelbrot set generator that outputs iteration counts as control signals.

**Signal Processing and Utilities:**
- **Morton**: Interleaves X and Y bits to produce Morton codes (Z-order curves), useful for spatial hashing and non-linear sequencing.
- **UniversalSlopeGenerator**: Produces configurable slope waveforms with adjustable rise and fall characteristics.
- **SmoothSteppedGenerator**: Generates smooth stepped envelopes that interpolate between discrete values.
- **Integrator**: A simple numerical integrator for cumulative signal processing.
- **Inverter**: Implements signal inversion using the formula `1 - x`, flipping modulation polarity.
- **Laplace**: Applies a Laplace filter for edge detection and high-frequency emphasis in control signals.
- **KineticShaper**: A non-linear waveshaper optimized for kinetic-type curves and physical modeling applications.
- **Transistor**: A simple transistor-style gain stage that introduces non-linear saturation characteristics.

### Delays

The delay category provides time-based effects:

- **Delay** ([`nallely/experimental/delays.py`](https://github.com/dr-schlange/nallely-midi/blob/main/nallely/experimental/delays.py)): A classic digital delay line with configurable feedback and time parameters.
- **ConveyorLine** ([`nallely/experimental/delays.py`](https://github.com/dr-schlange/nallely-midi/blob/main/nallely/experimental/delays.py)): A multi-tap conveyor-belt style delay that shifts samples through a moving buffer, creating rhythmic delay patterns.

## How to Enable Experimental Virtual Devices

You can activate experimental devices through the command line interface or programmatically via the Python API.

### CLI Activation

The command line parser defines the `--experimental` flag in [`nallely/cli.py`](https://github.com/dr-schlange/nallely-midi/blob/main/nallely/cli.py) (lines 45-48). When passed to `nallely run`, the flag forwards `include_experimental=True` to the runtime initialization (lines 96-103).

Run a Trevor session with the web UI and experimental devices enabled:

```bash
nallely run --with-trevor --serve-ui --experimental

```

Launch a standalone script that utilizes experimental devices:

```bash
nallely run --init my_patch.nly --experimental

```

### API Activation

When embedding nallely in Python applications, pass the boolean parameter directly to the startup function:

```python
from nallely.trevor import start_trevor

start_trevor(
    builtin_devices=False,
    include_experimental=True,  # Activates experimental virtual devices

    loaded_paths=[],            # Optional additional library paths

)

```

Without this flag, nallely only loads the stable built-in MIDI devices and core virtual devices defined in `nallely/core`.

## Manual Import for Testing and Development

For unit testing or granular control, import experimental devices directly without enabling the full experimental suite:

```python
from nallely.experimental.maths import HenonProjector

device = HenonProjector(freq=2.0)
device.start()

```

This approach bypasses the automatic registration system while allowing access to specific chaotic generators or fractal projectors defined in the experimental modules.

## Summary

- **Experimental virtual devices** reside in `nallely/experimental` and extend `VirtualDevice`, including chaotic generators like `LorenzProjector` and routers like `BroadcastRAM8`.
- **Activation requires** the `--experimental` CLI flag or `include_experimental=True` API argument, which triggers dynamic importing in [`nallely/trevor/trevor_bus.py`](https://github.com/dr-schlange/nallely-midi/blob/main/nallely/trevor/trevor_bus.py).
- **Categories include** routers, random patchers, mathematical attractors/fractals, and specialized delay lines.
- **Direct import** works for individual testing: `from nallely.experimental.maths import HenonProjector`.
- **Default behavior** excludes these devices to ensure system stability; they must be explicitly enabled per session.

## Frequently Asked Questions

### What is the difference between built-in devices and experimental virtual devices in nallely?

Built-in devices include stable MIDI implementations for hardware like the Korg Minilogue and NTS-1, plus core virtual devices in `nallely/core`. Experimental virtual devices are advanced modules—such as strange attractor generators and random patchers—that reside in `nallely/experimental` and require explicit activation via the `--experimental` flag because they may consume additional resources or implement unstable mathematical algorithms.

### How does the `--experimental` flag technically enable devices?

When detected in [`nallely/cli.py`](https://github.com/dr-schlange/nallely-midi/blob/main/nallely/cli.py), the flag passes `include_experimental=True` to `start_trevor` or `launch_standalone_script`. Inside [`nallely/trevor/trevor_bus.py`](https://github.com/dr-schlange/nallely-midi/blob/main/nallely/trevor/trevor_bus.py) (lines 828-831), this boolean triggers `from nallely.experimental import *`, which executes the package's [`__init__.py`](https://github.com/dr-schlange/nallely-midi/blob/main/__init__.py) and registers all `VirtualDevice` subclasses found in modules like [`maths.py`](https://github.com/dr-schlange/nallely-midi/blob/main/maths.py), [`routers.py`](https://github.com/dr-schlange/nallely-midi/blob/main/routers.py), and [`delays.py`](https://github.com/dr-schlange/nallely-midi/blob/main/delays.py).

### Can I use experimental devices without the Trevor bus or CLI?

Yes. Individual experimental devices can be imported directly from their source modules for testing or custom implementations. For example, `from nallely.experimental.delays import Delay` allows instantiation outside the standard device discovery system, though you must manually manage the device's lifecycle with `.start()` and parameter connections.

### Are experimental virtual devices stable for production use?

Experimental devices are marked as such because they implement cutting-edge algorithms—such as high-resolution Buddhabrot rendering or chaotic Lorenz attractors—that may have higher CPU requirements or less predictable output ranges than core devices. While functional, they lack the stability guarantees of built-in MIDI devices and should be tested thoroughly in your specific signal chain before deployment in critical performance environments.