Project ORCHID is the low-level micro-architectural execution core of the RAMNET protocol. It provides the mathematical proof-of-concepts, dynamic assembly generators, and scheduling blueprints required to bypass the digital memory wall and run bare-metal computation at zero-stall efficiency.
Note
Standalone Architecture: While ORCHID was intentionally designed and optimized as the foundational low-level execution engine for the decentralized compute mesh of the RAMNET Protocol, it is engineered as a completely decoupled, standalone layer. Its core scheduler, cache-line saturation modules, and micro-kernel code emitters can be utilized independently across the industry for high-concurrency systems and bare-metal orchestration.
- Concept originator: Teppei Oohira / 大平鉄兵 (@gatchimuchio)
- Designed the initial CPU cache line locality proofs, assembly code generation matrices, and parallel multi-memory bank role-scheduling modules.
- Core Architecture & Maintainer: Kevin West / @westkevin12
- Directs overall system integration, maintains the execution environments, and manages the architectural roadmap for deployment within the RAMNET distributed compute mesh.
The absolute base foundation, research primitives, and original codebase layout can be found preserved on the legacy archive branch:
👉 View the Baseline Concept Code (tree/gatchimuchio-original)
Under identical, mathematically verified logical execution constraints (512x512 matrix size, double-triplicate verification, and total 64 MiB L1-L3 cache flushes between timing runs), the locality-aligned (I-K-J) memory mapping sweeps demonstrate exceptionally high performance improvements. Badges below are dynamically parsed from current timing sweeps:
| Metric | Speedup |
|---|---|
| Minimum Speedup |  |
| Median Speedup |  |
| Maximum Speedup |  |
| Mean Speedup |  |
To ensure professional documentation standards and maintain a clean, readable quickstart guide, Project ORCHID's deep technical designs, mathematical formulations, and nested folder blueprints have been centralized:
👉 Read the Master Architecture Blueprint (docs/ARCHITECTURE.md)
- The Go/Python Hybrid Split: Understanding how the Python client SDK prepares/decomposes graphs and the native Go daemon schedules execution payloads.
- Mathematical Formulations: Technical detail on why loop striding swap-layouts (
I-K-JvsI-J-K) saturate CPU caches, alongside the CADENCE parallel banking role-routing models. - Repository File Blueprint: A detailed responsibility description of every single directory, file, and utility script.
- Continuous Quality Orchestration: How Docker Compose, Astral
uvvirtual environments, and SonarQube static analyzer suites interact to verify system integrity.
Project ORCHID features a top-level Makefile acting as the central developer control panel. Instead of navigating subfolders and invoking standalone shell scripts, use these standardized commands:
Automatically provisions the sandboxed Python 3.10 virtual environment, installs the modular orchid Python SDK in editable development mode (uv pip install -e .), and runs first-run diagnostic verification checks.
make setupExecutes concurrent Go scheduling unit tests, compiles x86-64 assembly locality cache-line saturation benchmarks, and generates parallel banked STREAM-Triad simulation logs.
make testCompiles the high-concurrency Go node scheduler daemon into a standalone, bare-metal native binary at build/orchid-daemon.
make buildBuilds, spins up, and executes the entire multi-language ORCHID stack in isolated Docker containers, volume-syncing generated benchmarks back to your local host filesystem.
make docker-upTip
To run the container network in the background (detached mode), use the -d flag:
docker compose up -d --buildYou can follow and stream the logs live by executing:
docker compose logs -fOr isolate output to a single service (e.g., the cache locality timings):
docker compose logs -f orchid-locality-benchmarkInstantly purges temporary compile targets (locality/build/), telemetry traces (evidence/), and Python __pycache__ artifacts.
make cleanProject ORCHID publishes two distinct, optimized container flavors to the GitHub Container Registry under a single repository space to meet different operational environments:
- Target Stage:
release-hardened - Compiled Control Plane: Compiles the
orchidPython SDK plane into optimized C/C++ extension modules (.so) using Nuitka. - Source Protection: Purges raw
.pyscripts inside the package namespace to prevent code extraction. - High Performance: Execution loops for micro-kernels and role-scheduling simulators execute at native C speeds.
- Target Stage:
developer - Raw Python SDK: Features standard, raw Python code inside the package structure.
- Developer Toolset: Includes the full Astral
uvpackage manager, volume mount options, and system diagnostic sweeps for active engineering.
To ensure a deterministic, high-performance workspace out-of-the-box, Project ORCHID coordinates the following enterprise-grade tooling layers:
The Python control plane is structured as a modular, distributable Python package using the hatchling build-backend. You can build it into wheels (uv build) or import modules programmatically:
from orchid.assembler import Spec, emit_locality- x86-64 micro-kernel code emitter.from orchid.simulator import BankedMemoryScheduler- Stream-Triad memory bank role simulator.from orchid.aggregator import parse_and_summarize- Statistical result parser.
We use Astral uv for lightning-fast Python version lock-in and virtual environment sandboxing. It guarantees that the correct minimum Python version (>= 3.10) is isolated and executed in .venv/ without polluting your global system.
- VS Code Settings: Opening this folder in VS Code automatically reads the pre-configured
.vscode/settings.json, instantly targeting the.venv/bin/pythoninterpreter. - Multi-Language Quality Gates (SonarQube): We use SonarQube for enterprise-grade quality gates and security audits across all of ORCHID's modules (Python, Go, C, and Bash). Standard configuration properties are loaded from
sonar-project.properties. Developers are highly encouraged to install the SonarLint extension in their IDE for live real-time analysis logs.
"Intelligence requires every available joule."