### Generate Optimization Script with Honegumi

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Demonstrates how to use the Honegumi class's generate method with a configured OptionsModel to produce an optimization script. The output includes setup for the Ax Client, defining parameters, objectives, and loading training data.

```python
# Assuming hg and options_model are defined
# result = hg.generate(options_model)
#
# print(result)
```

--------------------------------

### Install Honegumi and Ax Platform (Python)

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Installs the honegumi and ax-platform Python packages. It pins specific versions to ensure compatibility, which is crucial for reliable execution of Bayesian optimization tasks.

```python
import sys
IN_COLAB = 'google.colab' in sys.modules
if IN_COLAB:
    %pip install honegumi==0.4.1 ax-platform==0.4.3

```

--------------------------------

### Install Ax Platform and optional Matplotlib

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Installs the Ax Platform and Matplotlib for visualization using pip. The installation of Matplotlib is conditional.

```python
# %pip install ax-platform {% if visualize %}matplotlib{% endif %}
```

--------------------------------

### Batch Optimization Step (Python)

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Shows a batch optimization step, retrieving multiple trials at once. It defines a batch size, gets the next batch of trials, iterates through each trial in the batch, extracts parameters, calculates results, and completes each trial.

```python
batch_size = 2
parameterizations, optimization_complete = ax_client.get_next_trials(batch_size)
for trial_index, parameterization in list(parameterizations.items()):
    # extract parameters 
    x1 = parameterization["x1"]
    x2 = parameterization["x2"]
    results = objective_function(
        x1, x2
        )
    ax_client.complete_trial(trial_index=trial_index, raw_data=results)
```

--------------------------------

### Define Training Data with Constraints

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Sets up initial training data for the optimization experiment. Includes comments noting the satisfaction of compositional and order constraints.

```python
# Define the training data
{% if composition_constraint %}
# note that for this training data, the compositional constraint is satisfied
{% endif %}
{% if order_constraint %}
```

--------------------------------

### Get Next Trial and Complete with Results - Python

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

This snippet illustrates how to use the AxClient to obtain the next trial for optimization. It retrieves a parameterization and trial index, extracts specific parameters (x1, x2), calculates results using the 'branin' function, and then completes the trial with these results.

```python
for i in range(19):

    parameterization, trial_index = ax_client.get_next_trial()

    # extract parameters
    x1 = parameterization["x1"]
    x2 = parameterization["x2"]

    results = branin(x1, x2)
    ax_client.complete_trial(trial_index=trial_index, raw_data=results)
```

--------------------------------

### Existing Data Configuration

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Determines whether to fit the surrogate model to historical data prior to optimization. Including data can improve model starting points and convergence speed, while excluding it avoids potential bias or noise.

```python
{
  'disable': False,
  'display_name': 'Existing Data',
  'hidden': False,
  'name': 'existing_data',
  'options': [False, True],
  'tooltip': 'Choose whether to fit the surrogate model to previous data before starting the optimization process. Including historical data may give your model a better starting place and potentially speed up convergence. Conversely, excluding existing data means starting the optimization from scratch, which might be preferred in scenarios where historical data could introduce bias or noise into the optimization process. Consider the relevance and reliability of your existing data when making your selection.'
}
```

--------------------------------

### Import Multi-Task Learning Components

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Imports specific components for multi-task learning, including a registry for task-specific models and observation features.

```python
from ax.modelbridge.registry import Specified_Task_ST_MTGP_trans
from ax.core.observation import ObservationFeatures
```

--------------------------------

### Import Ax Client and Core Components

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Imports necessary components from the Ax Platform for setting up and running experiments. Conditional imports are used based on visualization and data availability.

```python
import numpy as np
import pandas as pd
from ax.service.ax_client import AxClient, ObjectiveProperties
{% if visualize %}import matplotlib.pyplot as plt{% endif %}
{% else %}
import numpy as np
from ax.service.ax_client import AxClient, ObjectiveProperties
{% endif %}
```

--------------------------------

### Clone Repository and Install Project

Source: https://honegumi.readthedocs.io/en/latest/contributing

These commands guide the user to clone the Honegumi repository from GitHub and install the project in editable mode for development. It also installs essential build tools for package management.

```shell
git clone git@github.com:YourLogin/honegumi.git
cd honegumi
pip install -U pip setuptools -e .
```

--------------------------------

### Initialize Honegumi and OptionsModel

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Illustrates the initialization of the Honegumi class with template directories and names, followed by the creation of an OptionsModel instance to configure optimization parameters like objective type and existing data usage.

```python
from pprint import pprint

# Assuming cst, option_rows, script_template_dir, core_template_dir, script_template_name, core_template_name are defined
# hg = Honegumi(
#     cst,
#     option_rows,
#     script_template_dir=script_template_dir,
#     core_template_dir=core_template_dir,
#     script_template_name=script_template_name,
#     core_template_name=core_template_name,
# )
# options_model = hg.OptionsModel(
#     objective="multi", linear_constraint=False, existing_data=True
# )
#
# pprint(options_model.model_dump())
```

--------------------------------

### Custom Threshold Configuration

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Allows the application of custom thresholds to objectives in multi-objective optimization problems, guiding the algorithm towards solutions meeting specific criteria. Excluding thresholds allows for broader exploration but may yield less optimal results.

```python
{
  'disable': False,
  'display_name': 'Custom Threshold',
  'hidden': False,
  'name': 'custom_threshold',
  'options': [False, True],
  'tooltip': 'Choose whether to apply custom thresholds to objectives in a multi-objective optimization problem (e.g. a minimum acceptable strength requirement for a material). Setting a threshold on an objective guides the optimization algorithm to prioritize solutions that meet or exceed these criteria. Excluding thresholds enables greater exploration of the design space, but may produce sub-optimal solutions. Consider whether threshold values reflect the reality or expectations of your optimization task when selection this option.'
}
```

--------------------------------

### Access Honegumi Constants

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Demonstrates how to access and print specific constants from the Honegumi project's cst module, such as OBJECTIVE_OPT_KEY and LINEAR_CONSTRAINT_KEY.

```python
import cst

print(cst.OBJECTIVE_OPT_KEY)
print(cst.LINEAR_CONSTRAINT_KEY)
```

--------------------------------

### Import Honegumi and Print Option Rows

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

This snippet demonstrates importing necessary classes from the Honegumi library and the Ax Platform utilities. It then prints the `option_rows` variable, which contains configurations for optimization parameters.

```python
from pprint import pprint
from honegumi.core._honegumi import Honegumi
from honegumi.ax.utils import constants as cst
from honegumi.ax._ax import option_rows

pprint(option_rows)
```

--------------------------------

### Get Best Optimization Parameters with AxClient

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Retrieves the best parameters found during an optimization campaign using the `ax_client.get_best_parameters()` method. It returns the optimal parameterization and associated objective values.

```python
from multi_objective_existing_data import ax_client

ax_client.get_best_parameters()
```

--------------------------------

### Attach and Complete Trials with Existing Data - Python

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

This snippet shows how to add pre-existing data to the AxClient. It iterates through training data, attaches each parameterization as a trial, and then completes the trial with the corresponding raw data.

```python
for i in range(n_train):
    parameterization = X_train.iloc[i].to_dict()

    ax_client.attach_trial(parameterization)
    ax_client.complete_trial(trial_index=i, raw_data=y_train[i])
```

--------------------------------

### List Honegumi Constants

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Displays a list of all available constants defined within the Honegumi project's cst module. These constants are used to configure various aspects of the optimization process.

```python
import cst
dir(cst)
```

--------------------------------

### Get Best Parameters (Single Objective) (Python)

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Retrieves the best parameters and corresponding metrics after a single-objective optimization process. This is typically called after completing all optimization iterations.

```python
best_parameters, metrics = ax_client.get_best_parameters()
```

--------------------------------

### Get Pareto Optimal Parameters (Multi Objective) (Python)

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Retrieves the Pareto optimal set of parameters after a multi-objective optimization process. This is useful for understanding the trade-offs between different objectives.

```python
pareto_results = ax_client.get_pareto_optimal_parameters()
```

--------------------------------

### Batch Optimization with Composition Constraint (Python)

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Shows a batch optimization step that includes a composition constraint. It retrieves a batch of trials, extracts parameters, calculates the third parameter (x3) based on the constraint, and then completes each trial.

```python
batch_size = 2
parameterizations, optimization_complete = ax_client.get_next_trials(batch_size)
for trial_index, parameterization in list(parameterizations.items()):
    # extract parameters 
    x1 = parameterization["x1"]
    x2 = parameterization["x2"]
    x3 = total - (x1 + x2) # composition constraint: x1 + x2 + x3 == total
    results = objective_function(
        x1, x2, x3
        )
    ax_client.complete_trial(trial_index=trial_index, raw_data=results)
```

--------------------------------

### Render Optimization Trace with AxClient

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Visualizes the optimization performance over iterations using `ax_client.get_optimization_trace()`. It optionally accepts the true objective optimum for comparison and renders the plot using the 'render' utility.

```python
from ax.utils.measurement.synthetic_functions import branin

render(
    ax_client.get_optimization_trace(objective_optimum=branin.fmin)
)
```

--------------------------------

### Multi-Task Batch Optimization with Composition Constraint (Python)

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Demonstrates a batch optimization step for multi-task scenarios with a composition constraint. It retrieves trials, extracts parameters including task, calculates x3 based on the constraint, and completes each trial.

```python
batch_size = 2
parameterizations, optimization_complete = ax_client.get_next_trials(batch_size, fixed_features=ObservationFeatures({"task": "A" if i % 2 == 0 else "B"}))
for trial_index, parameterization in list(parameterizations.items()):
    # extract parameters 
    x1 = parameterization["x1"]
    x2 = parameterization["x2"]
    x3 = total - (x1 + x2) # composition constraint: x1 + x2 + x3 == total
    task = parameterization["task"]
    results = objective_function(
        x1, x2, x3, task
        )
    ax_client.complete_trial(trial_index=trial_index, raw_data=results)
```

--------------------------------

### Locate Honegumi Template Files

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Shows how to programmatically find the directory paths for Honegumi's template files, main.py.jinja and honegumi.html.jinja, using the honegumi package's __path__ attribute.

```python
from os import path
import honegumi

script_template_dir = honegumi.ax.__path__[0]
core_template_dir = honegumi.core.__path__[0]

script_template_name = "main.py.jinja"
core_template_name = "honegumi.html.jinja"

print(path.join(script_template_dir, script_template_name))
print(path.join(core_template_dir, core_template_name))
```

--------------------------------

### Visualize Results Configuration

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Controls the inclusion of visualization tools for monitoring optimization progress, such as objective value convergence and model uncertainty. Visualizations aid in tracking and identifying issues but may incur minor computational overhead.

```python
{
  'disable': False,
  'display_name': 'Visualize Results',
  'hidden': False,
  'name': 'visualize',
  'options': [False, True],
  'tooltip': 'Choose whether to include visualization tools for tracking optimization progress. The default visualizations display key performance metrics like optimization traces and model uncertainty (e.g. objective value convergence over time). Including visualizations helps monitor optimization progress and identify potential issues, but may add minor computational overhead. Consider whether real-time performance tracking would '
}
```

--------------------------------

### Define Multi-Task Branin Function

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Extends the Branin function for multi-task learning by adding task-specific penalties to the primary objective.

```python
def branin_mt(x1, x2{% if composition_constraint %}, x3{% endif %}{% if categorical %}, c1{% endif %}, task):
    y = float(
        (x2 - 5.1 / (4 * np.pi**2) * x1**2 + 5.0 / np.pi * x1 - 6.0) ** 2
        + 10 * (1 - 1.0 / (8 * np.pi)) * np.cos(x1)
        + 10
    )

    # if multi-task, add a penalty based on task
    penalty_lookup = {"A": 1.0, "B": 1.1 + x1 + 2*x2}
    y += penalty_lookup[task]

    {% if composition_constraint -%}
    # Contrived way to incorporate x3 into the objective
    y = y * (1 + 0.1 * x1 * x2 * x3)
    {%- endif %}

    {% if categorical %}
    # add a made-up penalty based on category
    penalty_lookup = {"A": 1.0, "B": 0.0, "C": 2.0}
    y += penalty_lookup[c1]
    {% endif %}
    return y
```

--------------------------------

### Import BoTorch Acquisition Function

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Imports the UpperConfidenceBound acquisition function from BoTorch, typically used with custom Bayesian optimization models.

```python
from botorch.acquisition import UpperConfidenceBound
```

--------------------------------

### Multi-Task Batch Optimization Step (Python)

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Demonstrates a batch optimization step for multi-task scenarios. It defines a batch size and retrieves multiple trials with task-specific features. It then iterates through the batch, extracts parameters including the task, calculates results, and completes each trial.

```python
batch_size = 2
parameterizations, optimization_complete = ax_client.get_next_trials(batch_size, fixed_features=ObservationFeatures({"task": "A" if i % 2 == 0 else "B"}))
for trial_index, parameterization in list(parameterizations.items()):
    # extract parameters 
    x1 = parameterization["x1"]
    x2 = parameterization["x2"]
    task = parameterization["task"]
    results = objective_function(
        x1, x2, task
        )
    ax_client.complete_trial(trial_index=trial_index, raw_data=results)
```

--------------------------------

### Define Multi-Objective, Multi-Task Branin Function

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Combines multi-objective and multi-task capabilities for the Branin function, including task-specific penalties for both objectives.

```python
def branin_moo_mt(x1, x2{% if composition_constraint %}, x3{% endif %}{% if categorical %}, c1{% endif %}, task):
    y = float(
        (x2 - 5.1 / (4 * np.pi**2) * x1**2 + 5.0 / np.pi * x1 - 6.0) ** 2
        + 10 * (1 - 1.0 / (8 * np.pi)) * np.cos(x1)
        + 10
    )

    # if multi-task, add a penalty based on task
    penalty_lookup = {"A": 1.0, "B": 1.1 + x1 + 2*x2}
    y += penalty_lookup[task]

    {% if composition_constraint -%}
    # Contrived way to incorporate x3 into the objective
    y = y * (1 + 0.1 * x1 * x2 * x3)
    {%- endif %}

    {% if categorical %}
    # add a made-up penalty based on category
    penalty_lookup = {"A": 1.0, "B": 0.0, "C": 2.0}
    y += penalty_lookup[c1]
    {% endif %}
    # second objective has x1 and x2 swapped
    y2 = float(
        (x1 - 5.1 / (4 * np.pi**2) * x2**2 + 5.0 / np.pi * x2 - 6.0) ** 2
        + 10 * (1 - 1.0 / (8 * np.pi)) * np.cos(x2)
        + 10
    )
    # if multi-task, add a penalty based on task for second objective
    penalty_lookup_2 = {"A": 0.8, "B": 0.9 + 2*x1 + x2}
    y2 += penalty_lookup_2[task]

    {% if composition_constraint -%}
    # Contrived way to incorporate x3 into the second objective
    y2 = y2 * (1 - 0.1 * x1 * x2 * x3)
    {%- endif %}
    {% if categorical %}
    # add a made-up penalty based on category
    penalty_lookup = {"A": 0.0, "B": 2.0, "C": 1.0}
    y2 += penalty_lookup[c1]
    {% endif %}
    return {obj1_name: y, obj2_name: y2}
```

--------------------------------

### Python: Log Ax Trial Completion and Parameterization

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Logs Ax experiment trial completion, including the trial number, data (like 'branin' values), and custom parameterizations. This helps track the progress of optimization experiments.

```python
[INFO 03-01 18:52:11] ax.service.ax_client: Completed trial 0 with data: {'branin': (48.620235, None)}.
[INFO 03-01 18:52:11] ax.core.experiment: Attached custom parameterizations [{'x1': 0.0, 'x2': 6.2}] as trial 1.
[INFO 03-01 18:52:11] ax.service.ax_client: Completed trial 1 with data: {'branin': (19.642113, None)}.
[INFO 03-01 18:52:11] ax.core.experiment: Attached custom parameterizations [{'x1': 5.9, 'x2': 2.0}] as trial 2.
[INFO 03-01 18:52:11] ax.service.ax_client: Completed trial 2 with data: {'branin': (19.70361, None)}.
[INFO 03-01 18:52:11] ax.core.experiment: Attached custom parameterizations [{'x1': 1.5, 'x2': 2.0}] as trial 3.
[INFO 03-01 18:52:11] ax.service.ax_client: Completed trial 3 with data: {'branin': (14.301934, None)}.
[INFO 03-01 18:52:11] ax.core.experiment: Attached custom parameterizations [{'x1': 1.0, 'x2': 9.0}] as trial 4.
[INFO 03-01 18:52:11] ax.service.ax_client: Completed trial 4 with data: {'branin': (35.100744, None)}.
```

--------------------------------

### Import Generation Strategy Components

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Imports components for defining custom generation strategies, including model bridges and generation step configurations. This is conditionally enabled.

```python
from ax.modelbridge.factory import Models
from ax.modelbridge.generation_strategy import GenerationStep, GenerationStrategy
```

--------------------------------

### Python Console Script Setup and Logging

Source: https://honegumi.readthedocs.io/en/latest/_modules/honegumi/ax/_ax

This snippet demonstrates how to set up a Python console script using `setup.cfg` and `pip`. It also includes a logging configuration with a fallback function for environments where `pyscript.window` is not available.

```python
"""
This is a skeleton file that can serve as a starting point for a Python
console script. To run this script uncomment the following lines in the
``[options.entry_points]`` section in ``setup.cfg``::

    console_scripts =
         fibonacci = ax.skeleton:run

Then run ``pip install .`` (or ``pip install -e .`` for editable mode)
which will install the command ``fibonacci`` inside your current environment.

Besides console scripts, the header (i.e. until ``_logger``...) of this file can
also be used as template for Python modules.

Note:
    This file can be renamed depending on your needs or safely removed if not needed.

References:
    - https://setuptools.pypa.io/en/latest/userguide/entry_point.html
    - https://pip.pypa.io/en/stable/reference/pip_install
"""

import logging

import honegumi.ax.utils.constants as cst
import honegumi.core.utils.constants  # noqa: F401
from honegumi import __version__  # noqa: F401

# from jinja2 import Environment, FileSystemLoader

__author__ = "sgbaird"
__copyright__ = "sgbaird"
__license__ = "MIT"

_logger = logging.getLogger(__name__)

try:
    from pyscript import window

    log_fn = window.console.log
except Exception:



[docs]
    def log_fn(x):
        return x



    # log_fn = lambda x: x

# ---- Python API ----
# The functions defined in this section can be imported by users in their
# Python scripts/interactive interpreter, e.g. via
# `from honegumi.ax.skeleton import fib`,

```

--------------------------------

### Multi-Task Single-Trial Optimization Step (Python)

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Demonstrates a single optimization step for multi-task Bayesian optimization. It retrieves the next trial's parameters, including a 'task' feature, extracts parameters, and calculates results using an objective function before completing the trial.

```python
parameterization, trial_index = ax_client.get_next_trial(fixed_features=ObservationFeatures({"task": "A" if i % 2 == 0 else "B"}))
    # extract parameters 
    x1 = parameterization["x1"]
    x2 = parameterization["x2"]
    task = parameterization["task"]
    results = objective_function(
        x1, x2, task
        )
    ax_client.complete_trial(trial_index=trial_index, raw_data=results)
```

--------------------------------

### Synchrony Configuration (Single vs. Batch)

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Configures the evaluation strategy for Bayesian optimization campaigns, allowing selection between single-point or batch evaluations. Single evaluations offer precise control but are slower, while batch evaluations process multiple solutions in parallel for faster, though potentially less specific, optimization cycles.

```python
{
  'disable': False,
  'display_name': 'Synchrony',
  'hidden': False,
  'name': 'synchrony',
  'options': ['Single', 'Batch'],
  'tooltip': 'Choose whether to perform <a href=\'curriculum/concepts/batch/single-vs-batch.md\'>single or batch evaluations</a> for your Bayesian optimization campaign. Single evaluations analyze one candidate solution at a time, offering precise control and adaptability after each trial at the expense of more compute time. Batch evaluations, however, process several solutions in parallel, significantly reducing the number of optimization cycles but potentially diluting the specificity of adjustments. Batch evaluation is helpful in scenarios where it is advantageous to test several solutions simultaneously. Consider the nature of your evaluation tool when selecting between the two options.'
}
```

--------------------------------

### Python: Log Ax New Trial Generation with Models

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Logs the generation of new trials in an Ax experiment, specifying the parameters and the model used (e.g., Sobol, BoTorch). This is crucial for understanding the search strategy employed.

```python
[INFO 03-01 18:52:11] ax.service.ax_client: Generated new trial 5 with parameters {'x1': 9.587288, 'x2': 5.531802} using model Sobol.
[INFO 03-01 18:52:11] ax.service.ax_client: Completed trial 5 with data: {'branin': (9.029266, None)}.
[INFO 03-01 18:52:11] ax.service.ax_client: Generated new trial 6 with parameters {'x1': 0.837337, 'x2': 2.174816} using model Sobol.
[INFO 03-01 18:52:11] ax.service.ax_client: Completed trial 6 with data: {'branin': (23.10046, None)}.
[INFO 03-01 18:52:11] ax.service.ax_client: Generated new trial 7 with parameters {'x1': -3.42233, 'x2': 7.725797} using model Sobol.
[INFO 03-01 18:52:11] ax.service.ax_client: Completed trial 7 with data: {'branin': (28.169217, None)}.
[INFO 03-01 18:52:11] ax.service.ax_client: Generated new trial 8 with parameters {'x1': 2.589625, 'x2': 4.998503} using model Sobol.
[INFO 03-01 18:52:11] ax.service.ax_client: Completed trial 8 with data: {'branin': (6.902961, None)}.
[INFO 03-01 18:52:11] ax.service.ax_client: Generated new trial 9 with parameters {'x1': 4.622433, 'x2': 8.986392} using model Sobol.
[INFO 03-01 18:52:11] ax.service.ax_client: Completed trial 9 with data: {'branin': (66.63855, None)}.
[INFO 03-01 18:52:13] ax.service.ax_client: Generated new trial 10 with parameters {'x1': 3.09954, 'x2': 3.291552} using model BoTorch.
[INFO 03-01 18:52:13] ax.service.ax_client: Completed trial 10 with data: {'branin': (1.373705, None)}.
[INFO 03-01 18:52:14] ax.service.ax_client: Generated new trial 11 with parameters {'x1': 10.0, 'x2': 3.0849} using model BoTorch.
[INFO 03-01 18:52:14] ax.service.ax_client: Completed trial 11 with data: {'branin': (1.949855, None)}.
[INFO 03-01 18:52:14] ax.service.ax_client: Generated new trial 12 with parameters {'x1': 10.0, 'x2': 0.0} using model BoTorch.
[INFO 03-01 18:52:14] ax.service.ax_client: Completed trial 12 with data: {'branin': (10.960889, None)}.
[INFO 03-01 18:52:15] ax.service.ax_client: Generated new trial 13 with parameters {'x1': 9.093204, 'x2': 3.047812} using model BoTorch.
[INFO 03-01 18:52:15] ax.service.ax_client: Completed trial 13 with data: {'branin': (1.62365, None)}.
[INFO 03-01 18:52:16] ax.service.ax_client: Generated new trial 14 with parameters {'x1': 9.449699, 'x2': 2.323648} using model BoTorch.
[INFO 03-01 18:52:16] ax.service.ax_client: Completed trial 14 with data: {'branin': (0.430609, None)}.
[INFO 03-01 18:52:17] ax.service.ax_client: Generated new trial 15 with parameters {'x1': 2.455093, 'x2': 3.541057} using model BoTorch.
```

--------------------------------

### Honegumi Optimization Setup

Source: https://honegumi.readthedocs.io/en/latest/curriculum/tutorials/batch/batch-fullybayesian

Initializes the AxClient and sets up the objective name for the optimization task. This is part of the setup for running a Bayesian optimization campaign using the Ax platform.

```python
import numpy as np
import pandas as pd
from ax.service.ax_client import AxClient, ObjectiveProperties
import matplotlib.pyplot as plt

from ax.modelbridge.factory import Models
from ax.modelbridge.generation_strategy import GenerationStep, GenerationStrategy


obj1_name = "corrosion_score" # MOD: update objective name
```

--------------------------------

### Linear Constraint Configuration

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Allows configuration of a linear constraint for optimization variables, enforcing a specific inequality rule. This option focuses trials on combinations adhering to the rule, potentially at the cost of flexibility.

```python
{
  'disable': False,
  'display_name': 'Linear Constraint',
  'hidden': False,
  'name': 'linear_constraint',
  'options': [False, True],
  'tooltip': 'Choose whether to implement a linear constraint over two or more optimization variables such that the linear combination of parameter values adheres to an inequality (e.g. 0.2*x_1 + x_2 < 0.1). This constraint focusses generated optimization trials on variable combinations that follow an enforced rule at the cost of flexibility. Consider whether such a constraint reflects the reality of variable interactions when selecting this option.'
}
```

--------------------------------

### Create and Activate Virtual Environment with Tox

Source: https://honegumi.readthedocs.io/en/latest/contributing

Sets up a dedicated virtual environment, activates it, installs tox, and then runs all tox environments. This is useful for isolating tox installations and troubleshooting.

```bash
virtualenv .venv
source .venv/bin/activate
.venv/bin/pip install tox
.venv/bin/tox -e all
```

--------------------------------

### Single-Trial Optimization Step (Python)

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Illustrates a single optimization step for Bayesian optimization. It retrieves the next trial's parameters and trial index, extracts relevant parameters (potentially including task-specific ones), calculates results using an objective function, and completes the trial.

```python
parameterization, trial_index = ax_client.get_next_trial()
    # extract parameters 
    x1 = parameterization["x1"]
    x2 = parameterization["x2"]
    results = objective_function(
        x1, x2
        )
    ax_client.complete_trial(trial_index=trial_index, raw_data=results)
```

--------------------------------

### Plotting Multi-Objective Results (General)

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Plots multi-objective experimental results, including the Pareto front, for general cases. It retrieves Pareto optimal parameters and visualizes observed data against the front.

```jinja
pareto = ax_client.get_pareto_optimal_parameters(use_model_predictions=False)
pareto_data = [p[1][0] for p in pareto.values()]
pareto = pd.DataFrame(pareto_data).sort_values(objectives[0])

ax.scatter(df[objectives[0]], df[objectives[1]], fc="None", ec="k", label="Observed")
ax.plot(pareto[objectives[0]], pareto[objectives[1]], color="#0033FF", lw=2, label="Pareto Front")
ax.set_xlabel(objectives[0])
ax.set_ylabel(objectives[1])
```

--------------------------------

### Read and Print Jinja Template File

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Reads the content of a Jinja template file located at 'main.py.jinja' and prints its content to the console. This is used to inspect the core logic generation of Honegumi scripts.

```python
from os import path

template_fpath = path.join(script_template_dir, "main.py.jinja")

with open(template_fpath, 'r') as f:
    print(f.read())
```

--------------------------------

### Add Existing Data to AxClient (Python)

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

This snippet shows how to attach existing training data (parameters and results) to the AxClient. It iterates through training data, converts parameter dictionaries, and optionally removes parameters based on composition constraints before completing the trial.

```python
for i in range(n_train):
    parameterization = X_train.iloc[i].to_dict()

    # remove x3, since it's hidden from search space due to composition constraint
    parameterization.pop('x3')

    ax_client.attach_trial(parameterization)
    ax_client.complete_trial(trial_index=i, raw_data=y_train[i])
```

--------------------------------

### Define Generation Strategy and Experiment - Python

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

This Python code defines a generation strategy for Bayesian optimization using the Ax client. It specifies optimization steps, models (SOBOL, GP), trial counts, and parallelism. It then creates an experiment with defined parameters, objectives, and constraints, including handling multi-task and categorical features.

```python
gs = GenerationStrategy(
    steps=[
        GenerationStep(
            model=Models.SOBOL,
            num_trials=4 + 2 * (categorical + composition_constraint) if not dummy else 3, # how many sobol trials to perform (rule of thumb: 2 * number of params)
            min_trials_observed=3,
            max_parallelism=5,
            model_kwargs={"seed": 999, "transforms": Specified_Task_ST_MTGP_trans} if task == "Multi" else {"seed": 999},
            model_gen_kwargs={"deduplicate": True} if task == "Multi" else {},
        ),
        GenerationStep(
            model=Models.{{ model_name }},
            num_trials=-1,
            max_parallelism=3,
            model_kwargs={
                "transforms": Specified_Task_ST_MTGP_trans
            },
        ),
    ]
)

ax_client = AxClient(generation_strategy=gs)
ax_client.create_experiment(
    parameters=[
        {"name": "x1", "type": "range", "bounds": [0.0, total] if composition_constraint else [-5.0, 10.0]},
        {"name": "x2", "type": "range", "bounds": [0.0, total] if composition_constraint else [0.0, 10.0]},
        {
            "name": "task",
            "type": "choice",
            "values": ["A", "B"],
            "is_task": True,
            "target_value": "B"
        } if task == "Multi" else {},
        {
            "name": "c1",
            "type": "choice",
            "is_ordered": False,
            "values": ["A", "B", "C"]
        } if categorical else {},
    ],
    objectives={
        obj1_name: ObjectiveProperties(minimize=True, threshold=25.0) if custom_threshold else ObjectiveProperties(minimize=True),
        obj2_name: ObjectiveProperties(minimize=True, threshold=15.0) if objective == "Multi" and custom_threshold else (ObjectiveProperties(minimize=True) if objective == "Multi" else None)
    },
    parameter_constraints=[
        "x1 + x2 <= 15.0", # example of a sum constraint, which may be redundant/unintended if composition_constraint is also selected
        f"x1 + x2 <= {total}", # reparameterized compositional constraint, which is a type of sum constraint
        "x1 <= x2", # example of an order constraint
        "1.0*x1 + 0.5*x2 <= 15.0", # example of a linear constraint. Note the lack of space around the asterisks
    ] if sum_constraint or composition_constraint or order_constraint or linear_constraint else [],
)
```

--------------------------------

### Logging Setup (Python)

Source: https://honegumi.readthedocs.io/en/latest/_modules/honegumi/core/_honegumi

Sets up basic logging configuration for the application. It configures the log format, level, and output stream (stdout).

```python
import logging
import sys

def setup_logging(loglevel):
    """Setup basic logging

    Args:
      loglevel (int): minimum loglevel for emitting messages
    """
    logformat = "[%(asctime)s] %(levelname)s:%(name)s:%(message)s"
    logging.basicConfig(
        level=loglevel, stream=sys.stdout, format=logformat, datefmt="%Y-%m-%d %H:%M:%S"
    )
```

--------------------------------

### Install and Configure Pre-commit Hooks

Source: https://honegumi.readthedocs.io/en/latest/contributing

This snippet shows how to install the 'pre-commit' package, which automates the execution of various code quality checks (hooks) before each commit. This helps maintain consistent code style and identify potential issues early.

```shell
pip install pre-commit
pre-commit install
```

--------------------------------

### Setup for Benchmarking Acquisition Functions in Ax

Source: https://honegumi.readthedocs.io/en/latest/curriculum/tutorials/benchmarking/benchmarking

This Python code sets up the necessary components for benchmarking acquisition functions using Ax. It imports required modules, defines the objective name, and configures parameters like the number of seeds for the experiment.

```python
import numpy as np
from ax.service.ax_client import AxClient, ObjectiveProperties

from ax.modelbridge.factory import Models
from ax.modelbridge.generation_strategy import GenerationStep, GenerationStrategy

# MOD: also import probability of improvement
from botorch.acquisition import ProbabilityOfImprovement, UpperConfidenceBound

obj1_name = "hartmann6" # MOD: update objective name

# MOD: remove the branin dummy objective function, we will use tabulated data

n_seeds = 3 # MOD: set number of seeds to loop over
```

--------------------------------

### Preview honegumi Documentation with Python http.server

Source: https://honegumi.readthedocs.io/en/latest/contributing

This command starts Python's built-in HTTP server to preview the compiled honegumi documentation. It serves files from the specified directory, allowing you to view the documentation in a web browser.

```bash
python3 -m http.server --directory 'docs/_build/html'
```

--------------------------------

### Write Python Script to File

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

This Python code snippet writes the content of a variable named 'result' to a file. The file is named 'multi_objective_existing_data.py'. This is useful for saving generated code or configurations to disk for later execution.

```python
script_name = "multi_objective_existing_data.py"

with open(script_name, "w") as f:
    f.write(result)

```

--------------------------------

### Python Imports and Setup for Honegumi Core

Source: https://honegumi.readthedocs.io/en/latest/_modules/honegumi/core/_honegumi

This snippet shows the necessary imports for the honegumi.core._honegumi module, including standard libraries, third-party packages like black and jinja2, and custom honegumi modules. It also includes logger setup and a conditional definition for log_fn.

```python
import argparse
import logging
import os
import sys
import warnings
from itertools import product
from typing import Any, Dict, List, Tuple, Union

from black import FileMode, format_file_contents
from jinja2 import Environment, FileSystemLoader, StrictUndefined
from pydantic import BaseModel, Field, create_model

import honegumi.core.utils.constants as core_cst
from honegumi import __version__
from honegumi.ax._ax import (
    add_model_specific_keys,
    extra_jinja_var_names,
    is_incompatible,
    model_kwargs_test_override,
    option_rows,
)

__author__ = "sgbaird"
__copyright__ = "sgbaird"
__license__ = "MIT"

_logger = logging.getLogger(__name__)


try:
    from pyscript import window

    log_fn = window.console.log
except Exception:



    def log_fn(x):
        return x
```

--------------------------------

### Composition Constraint Configuration

Source: https://honegumi.readthedocs.io/en/latest/curriculum/api-usage/honegumi-api-getting-started

Enables the inclusion of a composition constraint, ensuring that the sum of specified optimization variables does not exceed a given total. This is particularly useful for fabrication tasks where component quantities must sum to a specific value.

```python
{
  'disable': False,
  'display_name': 'Composition Constraint',
  'hidden': False,
  'name': 'composition_constraint',
  'options': [False, True],
  'tooltip': 'Choose whether to include a composition constraint over two or more optimization variables such that their sum does not exceed a specified total (e.g. ensuring the mole fractions of elements in a composition sum to one). This constraint is particularly relevant to fabrication-related tasks where the quantities of components must sum to a total. Consider whether such a constraint reflects the reality of variable interactions when selecting this option.'
}
```

--------------------------------

### Optimize Binder B Ceramic Formulation in Isolation using Ax Client

Source: https://honegumi.readthedocs.io/en/latest/curriculum/tutorials/multitask/multitask

This script demonstrates how to optimize the Binder B ceramic formulation in isolation using the Ax Client. It sets up a generation strategy with Sobol and BoTorch models, defines experiment parameters and objectives, attaches an initial trial, completes it with data, and then iteratively gets the next trial, completes it, and retrieves the best parameters. The script aims to validate the decision of using a multitask GP by comparing it to an isolated optimization.

```python
import numpy as np
from ax.service.ax_client import AxClient, ObjectiveProperties
from ax.core.generator_run import GenerationStep
from ax.modelbridge.registry import Models

# Assume strength_binderB is a defined function that returns the strength
# Example placeholder for strength_binderB:
def strength_binderB(ceram_frac, solv_frac, binder_frac, plast_frac):
    # Replace with actual model or calculation
    return 10 + ceram_frac * 5 + solv_frac * 2 - binder_frac * 3 + plast_frac * 1

obj1_name = "strength"

gs = GenerationStrategy(
    steps=[
        GenerationStep(
            model=Models.SOBOL,
            num_trials=4,
        ),
        GenerationStep(
            model=Models.BOTORCH_MODULAR,
            num_trials=-1,
        ),
    ]
)

ax_client = AxClient(generation_strategy=gs, verbose_logging=False, random_seed=42)

ax_client.create_experiment(
    parameters=[
        {"name": "ceram_frac",  "type": "range", "bounds": [0.5, 0.7]},
        {"name": "solv_frac",   "type": "range", "bounds": [0.2, 0.3]},
        {"name": "binder_frac", "type": "range", "bounds": [0.1, 0.2]},
        {"name": "plast_frac",  "type": "range", "bounds": [0.0, 0.01]},
    ],
    objectives={
        obj1_name: ObjectiveProperties(minimize=False),
    },
)

parameterization = {"ceram_frac": 0.62, "solv_frac": 0.3, "binder_frac": 0.1, "plast_frac": 0.01}
ax_client.attach_trial(parameterization)
ax_client.complete_trial(trial_index=0, raw_data={obj1_name: strength_binderB(**parameterization)})

for _ in range(6-1):

    p, trial_index = ax_client.get_next_trial()

    sigma = strength_binderB(p["ceram_frac"], p["solv_frac"], p["binder_frac"], p["plast_frac"])

    ax_client.complete_trial(trial_index=trial_index, raw_data=sigma)

best_parameters, metrics = ax_client.get_best_parameters()

print("\nisolated optimal strength:", metrics[0]['strength'])

```

--------------------------------

### Install ax-platform and matplotlib

Source: https://honegumi.readthedocs.io/en/latest/curriculum/tutorials/batch/batch-fullybayesian

Installs necessary libraries for Bayesian optimization and plotting, specifically for use within a Google Colab environment. This is a prerequisite for running the optimization script.

```python
try:
    import google.colab
    %pip install ax-platform matplotlib
except:
    print("Not running in Google Colab")
```

--------------------------------

### Install ax-platform for Google Colab

Source: https://honegumi.readthedocs.io/en/latest/curriculum/tutorials/sobo/sobo

Installs the ax-platform library, which is required for Bayesian optimization. This code snippet checks if it's running in Google Colab and installs the package if necessary.

```python
try:
    import google.colab
    %pip install ax-platform
except:
    print("Not running in Google Colab")
```

--------------------------------

### Initialize AxClient and Objective Name

Source: https://honegumi.readthedocs.io/en/latest/curriculum/tutorials/sobo/sobo

Initializes the AxClient for Bayesian optimization and sets the name for the primary objective. This is a common setup step when using the Ax platform for experiments.

```python
import numpy as np
import pandas as pd
from ax.service.ax_client import AxClient, ObjectiveProperties
import matplotlib.pyplot as plt

obj1_name = "printed_strength" # MOD: change objective name
```