Design Values: Evolving Your System¶

While Distributions represent the uncertainty you can't control (like wind or manufacturing tolerances), Design Values represent the parameters you can control. These are the knobs you turn to find the absolute best version of your system.

Optimization vs. Randomness¶

In a generic design workflow, we distinguish between two types of variables:

The Search Space API¶

Design values define a "Search Space" which is a mathematical boundary that an optimizer is allowed to explore. Every design variable in your registry must provide three things:

1. A Name: To track the variable across trials.
2. A Default: The initial "best guess" before the optimizer starts.
3. Bounds: The constraints (low/high or choices) that the solver must respect.

Supported Variable Types¶

Integrating with Solvers¶

One of the primary advantages of this toolkit is its Solver-Agnostic nature. Your model defines the variables once, and the system can automatically translate them into the specific language of different optimization libraries.

Optuna Integration (to_optuna)¶

For single-objective tuning, the variable suggests a value to a trial.

• Continuous: Uses Bayesian TPE or CMA-ES sampling.
• Refinement: The refine method allows the search space to "shrink" around the best known solution for more precision.

pymoo Integration (to_pymoo)¶

For multi-objective trade-offs, the variable generates a pymoo.core.variable object.

• Population-based: Allows for genetic operators (Crossover and Mutation).
• Pareto Front: Enables the discovery of the frontier of efficiency.

Usage Example¶

The following script demonstrates how to define a generic "System" and sample design variables into a registry for optimization.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

import logging

import numpy as np
import optuna

import stochas

# Setup logging
logging.basicConfig(level=logging.INFO)


class SystemModel(stochas.StochasBase):
    """A generic system model that uses design variables."""

    pass


def generate_system(model: SystemModel):
    # 1. Define a continuous float (e.g., structural stiffness)
    # The optimizer will explore between 50 and 500.
    stiffness = model.sample_design(
        stochas.DesignFloat(
            name=stochas.ValueName("k_stiffness"),
            low=50.0,
            high=500.0,
            stored_value=150.0,  # the initial guess
        )
    )

    # 2. Define an integer count (e.g., number of supports)
    n_supports = model.sample_design(
        stochas.DesignInt(
            name=stochas.ValueName("n_supports"), low=2, high=8, stored_value=4
        )
    )

    # 3. Define a categorical choice (e.g., material type)
    material = model.sample_design(
        stochas.DesignCategorical(
            name=stochas.ValueName("material"),
            choices=["aluminum", "steel", "titanium"],
            stored_value="steel",
        )
    )

    print(
        f"Generated System: {material} frame, {n_supports} supports, k={stiffness:.2f}"
    )


# --- Optimization Workflow ---

# 1. Create a model
model = SystemModel()

# 2. Discovery Pass: Map the design space
generate_system(model)
design_space = model.design

# 3. Translate to Optuna
study = optuna.create_study(direction="minimize")


def objective(trial):
    # Ask variables to suggest values to Optuna
    suggestions = {name: dv.to_optuna(trial) for name, dv in design_space.items()}

    # In a real run, you'd apply these 'suggestions' to the model.named registry
    # and execute your physics/cost simulation here.
    score = np.random.random()  # Placeholder for simulation result
    return score


study.optimize(objective, n_trials=10)

Search Space Refinement¶

When you reach the end of an optimization study, you may find that the "best" trial is settled in a specific neighborhood. The refine method automates the "zoom-in" process.

Given a refinement factor \(F \in (0, 1)\) and the best known value \(x_{best}\), the new bounds are calculated as: