Paramodel

Contract-first framework for pseudo-formal parameter modeling and systematic test sequence execution.

Overview

Paramodel provides a rigorous foundation for defining, compiling, and executing parametric studies. Built on algebraic principles with an emphasis on correctness, composability, and reproducibility.

With Paramodel, you can:

• Define type-safe Parameter Models to define parameters and domains to use in your studies.
• Define Parametric Test Models by defining parameter sets based on parameter models.
• Define test plans that express relationships between parameters and domains.
• Compile test plans into execution plans that can be executed in parallel.

In this context, a model is simply a specification for the parameters and deployable elements which they describe. You provide the implementation of these elements, and Paramodel takes care of the rest.

Key Features:

• Pure contract interfaces - Zero implementation coupling
• 8-stage compilation pipeline - TestPlan → ExecutionPlan transformation
• Concurrent execution engine - Resource-aware parallel execution with DAG scheduling
• Cardinality Management - Automatic derivation of element instances and cost optimization
• Technology Compatibility Kit (TCK) - Validates implementation conformance
• Java 25 - Leverages sealed interfaces, records, and pattern matching
• Diátaxis Documentation - Comprehensive tutorials, how-tos, reference, and explanation

Quick Start

1. Define Parameters and Domains

import io.nosqlbench.paramodel.mock.parameters.*;
import io.nosqlbench.paramodel.parameters.types.*;

// Create domains and parameters
var ops = IntegerParameter.range("threads", 1, 64);
var model = StringParameter.of("model", "gpt-.*");

2. Build TestPlan

import io.nosqlbench.paramodel.mock.plan.*;
import io.nosqlbench.paramodel.plan.*;

TestPlan plan = MockTestPlan.builder()
    .name("performance-study")
    .axis(MockAxis.of("concurrency", 1, 4, 16, 64)) // Major axis - minimizes churn
    .axis(MockAxis.of("model", "gpt-4", "gpt-4o"))
    .optimizationStrategy(OptimizationStrategy.PRUNE_REDUNDANT)
    .build();

3. Compile to ExecutionPlan

import io.nosqlbench.paramodel.engine.compiler.*;

Compiler compiler = DefaultCompiler.builder()
    .standardPipeline()
    .build();

ExecutionPlan executionPlan = compiler.compile(plan).executionPlan().orElseThrow();
System.out.println("Lifecycle steps: " + executionPlan.executionGraph().steps().size());
System.out.println("Estimated duration: " + executionPlan.estimatedDuration());

4. Run

import io.nosqlbench.paramodel.engine.execution.*;
import io.nosqlbench.paramodel.execution.Executor;

DefaultExecutor executor = DefaultExecutor.builder().build();
Executor.ExecutionResult result = executor.execute(executionPlan);

System.out.println("Success: " + result.isSuccess());
result.trialResults().forEach(tr -> 
    System.out.println("Trial " + tr.trial().id() + ": " + tr.status()));

Documentation

The documentation is organized following the Diátaxis framework:

📚 Concepts

Mental models and foundational ideas:

• Parameters and Domains
• Execution Plans
• Elements and Relationships
• Cardinality and Costs

🚀 Tutorials

Step-by-step learning guides:

• Getting Started
• First Test Plan
• Running Trials

🛠️ How-To Guides

Task-oriented recipes:

• Define Parameters
• Build a Test Plan
• Manage Cardinality
• Validate with TCK

📖 Reference

Technical lookup material:

• API Packages
• Contract Types
• Compilation Stages

💡 Explanation

Design decisions and architecture:

• Architecture
• Design Principles
• Immutability and Reproducibility

Requirements

• Java: 25+
• Maven: 3.9.0+

mvn clean install   # Build all modules
mvn clean verify    # Run tests + coverage + javadoc checks

License

Apache License 2.0