Ecosystem Setup

Overview

CoreToolkit's install script (scripts/install.sh) sets up the entire VOLT Labs ecosystem in one command:

• Clones every VOLT Labs repository, organized into tools/, plugins/, and app/ directories.
• Compiles all Foundational Algorithm plugins into statically-linked binaries inside Docker, ready to use.

Quick Start

curl -sSL https://raw.githubusercontent.com/voltlabs-research/CoreToolkit/main/scripts/install.sh | bash

Creates a voltlabs-ecosystem/ directory in the current working directory with the full ecosystem.

Requirements

Runs on Ubuntu / Debian (or Debian-based distros); installs missing system packages via apt:

What the Script Does

Steps run in order:

1. System Verification

• Verifies you're on a supported OS (Ubuntu/Debian).
• Checks and installs base packages: build-essential, cmake, git, python3, python3-pip, pkg-config, ca-certificates.
• Validates CMake ≥ 3.20 and a C++23-capable compiler.
• Installs Conan 2 via pip if not already available.
• Ensures Docker is installed.

2. Clone All Repositories

Cloned into a structured workspace:

voltlabs-ecosystem/
├── tools/
│   ├── CoreToolkit/
│   ├── VoltSDK/
│   ├── SpatialAssembler/
│   ├── HeadlessRasterizer/
│   └── LammpsIO/
├── plugins/
│   ├── StructureIdentification/
│   ├── AtomicStrain/
│   ├── CentroSymmetryParameter/
│   ├── CommonNeighborAnalysis/
│   ├── ClusterAnalysis/
│   ├── CoordinationAnalysis/
│   ├── DisplacementsAnalysis/
│   ├── ElasticStrain/
│   ├── GrainSegmentation/
│   ├── LineReconstructionDXA/
│   ├── OpenDXA/
│   └── PolyhedralTemplateMatching/
└── app/
    ├── Volt/
    └── ClusterDaemon/

Existing directories are skipped, so re-running the script is safe and picks up new repositories.

3. Build All Plugins

For each plugin in plugins/, the script runs a Docker-based build using CoreToolkit's Dockerfile.build:

1. A gcc:14-bookworm container installs CMake, Conan, and system dependencies.
2. CoreToolkit is exported as a Conan package inside the container.
3. Each plugin is compiled against CoreToolkit with Release optimizations (-O3, -mtune=generic, statically linked libstdc++ and libgcc). CPU-specific tuning (-march=native) is available but off by default; enable it with -DVOLT_ENABLE_NATIVE_OPTIMIZATIONS=ON.
4. The resulting binaries are extracted to the output directory.

Configuration

Environment variables:

WORK_DIR=~/my-volt BUILD_OUTPUT_DIR=~/my-volt/bin \
  curl -sSL https://raw.githubusercontent.com/voltlabs-research/CoreToolkit/main/scripts/install.sh | bash

Rebuild Without Cache

Pass --no-cache to rebuild plugin images without the Docker layer cache:

./voltlabs-ecosystem/tools/CoreToolkit/scripts/install.sh --no-cache

Build Output

Compiled plugin binaries land in the output directory (default <script dir>/out/). Each plugin is a standalone executable invoked with positional arguments:

<binary> <input_dump> <output_base> [plugin-specific flags]

• <input_dump> — path to the LAMMPS dump file to analyse.
• <output_base> — base path for result files; the binary appends suffixes and writes one or more Apache Parquet files (e.g. <output_base>_cluster_analysis.parquet, <output_base>_atoms.parquet).
• Plugin-specific flags vary by algorithm and follow their own conventions (e.g. --crystal_structure FCC --rmsd 0.1 for PTM-based plugins).

Plugins are normally invoked through their Python wrapper scripts, which handle binary location, flag filtering, and output validation.