### Example JCMoptimizer Configuration File

Source: https://optimizer.jcmwave.com/documentation/matlab/3.0.0/configuration/index

Provides a practical example of a JCMoptimizer configuration file, showcasing how to set general parameters, cloud-specific options like the API token, and local installation details.

```yaml
# General configurations
server_location: 'cloud'
dashboard: true
open_browser: false
output_precision: 1e-9

# Configuration for cloud-based JCMoptimizer
token: '240557813dcf4407194cf016ac0db43a4bdb16978ca47831833baeb869836cbf'

# Configuration for local JCMoptimizer
jcmoptimizer_dir: '~/JCMoptimizer/'
license_dir: '~/JCMsuite/license/'
save_dir: '~/studies/'


```

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

### Benchmark Evaluation Setup

Source: https://optimizer.jcmwave.com/documentation/python/2.1.3/_modules/jcmoptimizer/benchmark

Methods for setting up and running benchmark evaluations. This includes setting the objective function for evaluation and running the benchmark process.

```APIDOC
## Benchmark Evaluation Setup

### Description
Methods for setting up and running benchmark evaluations. This includes setting the objective function for evaluation and running the benchmark process.

### Method
POST

### Endpoint
N/A (Class methods)

### Methods
#### `set_evaluator(evaluator: Callable[..., Observation]) -> None`

##### Description
Set the function that maps design parameters to an :class:`Observation`.

##### Example
```python
def evaluate(study: Study, x1: float, x2: float) -> Observation:
    observation = study.new_observation()
    observation.add(x1**2 + x2**2)
    return observation
benchmark.set_evaluator(evaluate)
```

##### Parameters
- **evaluator** (Callable) - Required - Function handle for a function of the variable parameters that returns a corresponding :class:`Observation` object. The function must accept a ``"study"`` argument as well as an argument with the name of each design parameter and fixed environment parameter.

##### Notes
Call this function only after all studies have been added to the benchmark.

#### `run() -> None`

##### Description
Run the benchmark after the evaluator has been set (see :func:`~Benchmark.set_evaluator`).

##### Example
```python
benchmark.run()
```

##### Response
#### Success Response (200)
- **None** - This method does not return a value.

#### Error Handling
- **EnvironmentError**: Raised if a study encounters an error during execution.
```

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

### Configure JCMoptimizer Installation Directory

Source: https://optimizer.jcmwave.com/documentation/matlab/3.0.0/_sources/installation/index.rst

This YAML configuration snippet defines the installation directory for JCMoptimizer. This path is necessary for the JCMoptimizer server to locate its own installation files when running locally. Replace '/path/to/JCMoptimizer/' with your actual installation path.

```yaml
jcm_optimizer_dir: '/path/to/JCMoptimizer/'
```

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

### Create and Run Benchmark - Python

Source: https://optimizer.jcmwave.com/documentation/python/2.1.3/interface/index

Illustrates how to set up and run a benchmark comparison between multiple studies. It involves creating a benchmark, adding studies, setting an evaluator, running the benchmark, and then visualizing the results using matplotlib. This is useful for comparing the performance of different optimization strategies.

```python
benchmark = client.create_benchmark(num_average=6)
benchmark.add_study(study1)
benchmark.add_study(study2)
benchmark.set_evaluator(evaluate)
benchmark.run()
data = benchmark.get_data(x_type='num_evaluations',y_type='objective',
average_type='mean')

fig = plt.figure(figsize=(8,4))
for idx,name in enumerate(data['names']):
    X = data['X'][idx]
    Y = np.array(data['Y'][idx])
    std_error = np.array(data['sdev'][idx])/np.sqrt(6)
    p = plt.plot(X,Y,linewidth=2.0, label=name)
    plt.fill_between(X, Y-std_error, Y+std_error, alpha=0.2, color = p[0].get_color())

plt.legend(loc='upper right', ncol=1)
plt.grid()
plt.ylim([0.1,10])
plt.rc('font',family='serif')
plt.xlabel('number of iterations',fontsize=12)
plt.ylabel('average objective',fontsize=12)
plt.show()
```

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

### Least Square Fit Variable: Initial Parameters Example

Source: https://optimizer.jcmwave.com/documentation/python/2.0.5/drivers/FitVariable

Provides an example of how to set the initial values for the fit parameters when using the Least Square Fit Variable. This is crucial for guiding the optimization process.

```python
[
  0.5,
  0.2
]
```

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

### Setup and Create Optimization Studies

Source: https://optimizer.jcmwave.com/documentation/matlab/3.0.0/tutorials/benchmark

Initializes the optimizer server and client, defines the search space, environment, and constraints. It then creates multiple studies, each configured with a different driver, for benchmarking purposes. The studies are set up to run without opening a browser.

```matlab
server = jcmoptimizer.Server();
client = jcmoptimizer.Client('host', server.host);

% Definition of the search domain
design_space = {...
   struct('name', 'x1', 'type', 'continuous', 'domain', [-1.5,1.5]), ...
   struct('name', 'x2', 'type', 'continuous', 'domain', [-1.5,1.5]), ...
};

% Definition of fixed environment parameter
environment = {...     
   struct('name', 'radius', 'type', 'fixed', 'domain', 1.5) ...
};

% Definition of a constraint on the search domain
constraints = {... 
   struct('name', 'circle', 'expression', 'sqrt(x1^2 + x2^2) <= radius')...
};

%Creation of studies to benchmark against each other
studies = struct();
drivers = {"BayesianOptimization", "ActiveLearning", "CMAES", ...
           "DifferentialEvolution", "ScipyMinimizer"};
for i = 1:length(drivers)
   studies.(drivers{i}) = client.create_study( ...
        'design_space', design_space, ...
        'environment', environment, ...
        'constraints', constraints, ...
        'driver', drivers{i}, ...
        'study_name', drivers{i}, ...
        'study_id', sprintf("benchmark_%s", drivers{i}), ...
        'open_browser' , false ...
   );
end
```

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

### Configure JCMoptimizer License Directory

Source: https://optimizer.jcmwave.com/documentation/matlab/3.0.0/_sources/installation/index.rst

This YAML configuration snippet specifies the path to your JCMsuite license directory. This is required for running JCMoptimizer locally, as it needs to verify your JCMsuite installation. Update '/path/to/JCMsuite/license/' with your actual license path.

```yaml
license_dir: '/path/to/JCMsuite/license/'
```

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

### Local Server Initialization Options

Source: https://optimizer.jcmwave.com/documentation/python/3.0.0/_modules/jcmoptimizer/server

For local server instances, arguments related to the JCMoptimizer installation are used. This includes specifying the path to the JCMoptimizer directory, the license directory, the network port for the server to listen on, and timeout and retry parameters for server startup.

```python
server = Server(
    server_location='local',
    jcmoptimizer_dir="/path/to/JCMoptimizer",
    license_dir="/path/to/JCMsuite/license",
    port=4554,
    timeout=10,
    max_retries=3
)
```

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

### Get Driver State (Python)

Source: https://optimizer.jcmwave.com/documentation/python/2.0.5/drivers/CMAES

This example shows how to retrieve the state of the driver. By providing a 'path' argument, specific submodules or parameters can be targeted; omitting it returns the full state.

```python
best_sample = driver.get_state(path="best_sample")
```

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

### Get Driver Description (Python)

Source: https://optimizer.jcmwave.com/documentation/python/2.0.5/drivers/CMAES

This code retrieves a description of all modules and their parameters used by the driver. The output is a nested dictionary, and this example shows how to access the description of the first surrogate module.

```python
description = driver.describe()
print(description["members"]["surrogates"]["0"])
```

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

### Configure and Run JCMoptimizer Study

Source: https://optimizer.jcmwave.com/documentation/python/2.0.5/interface/index

Demonstrates how to configure and run a JCMoptimizer study. This includes setting up an evaluation function, configuring study parameters like max iterations and parallel jobs, and then running the optimization loop.

```python
def evaluate(study: Study, x1: float, x2: float) -> Observation:
    observation = study.new_observation()
    observation.add(x1**2+x2**2)
    return observation
study.configure(max_iter=30, num_parallel=3)

#Start optimization loop
study.set_evaluator(evaluate)
study.run()

#Alternatively, one can explicitly define an optimization loop
def acquire(suggestion: Suggestion) -> None:
   try: observation = evaluator(study, **suggestion.kwargs)
   except: study.clear_suggestion(suggestion.id, 'Evaluator failed')
   else: study.add_observation(observation, suggestion.id)
```

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

### Configure Surrogates with Gaussian Processes (Python)

Source: https://optimizer.jcmwave.com/documentation/matlab/2.1.3/drivers/ActiveLearning

Configures surrogate models using Gaussian Processes (GP). This example demonstrates setting up two GP surrogates, one for 'intensities' with 3 output dimensions and another for 'loss' with 1 output dimension. It also shows how to add observations to these models.

```python
study.configure('surrogates', {
   struct("type", "GP", "output_dim", 3, "name", "intensities"),
   struct("type", "GP", "output_dim", 1, "name", "loss"),
});

# Add some data to "intensities" model
obs = study.new_observation();
obs.add([1.0,2.0,3.0], "model_name", "intensities");
obs.add([6.0], "model_name", "loss");
study.add_observation(obs, "design_value", [7.4, 3.1]);
```

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

### Get JCMoptimizer Server Port (Python)

Source: https://optimizer.jcmwave.com/documentation/python/3.0.0/_modules/jcmoptimizer/server

This is a property getter for retrieving the port number on which the JCMoptimizer server is listening. It provides access to the server's network port after it has been successfully started.

```python
@property
def port(self) -> int:
    """The port that the server is listening on."""
```

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

### Matlab Get Benchmark Data and Plot

Source: https://optimizer.jcmwave.com/documentation/matlab/2.0.5/interface/index

Provides an example of retrieving benchmark data and plotting it using Matlab. It specifies data types for axes and averaging, then iterates through the data to create plots.

```matlab
data = benchmark.get_data('x_type','num_evaluations','y_type','objective',
              'average_type','mean');
plots = [];
for ii=1:length(data.names)
     X = data.X(ii,:);
     Y = data.Y(ii,:);
     plots(end+1) = plot(X,Y,'LineWidth',1.5);
end
legend(plots, data.names{:});

```

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

### Setup and Configuration of Optimization Studies

Source: https://optimizer.jcmwave.com/documentation/python/2.0.5/tutorials/benchmark

This snippet initializes the JCM Optimizer client, defines the design space, environment, and constraints for optimization studies. It then creates multiple studies, each with a different driver, and configures them with specific parameters like surrogate models, objectives, and stopping criteria.

```python
import sys,os
import numpy as np
import time
import matplotlib.pyplot as plt

jcm_optimizer_path = r"<JCM_OPTIMIZER_PATH>"
sys.path.insert(0, os.path.join(jcm_optimizer_path, "interface", "python"))
from jcmoptimizer import Server, Client, Study, Observation
server = Server()
client = Client(server.host)

# Definition of the search domain
design_space = [
    {'name': 'x1', 'type': 'continuous', 'domain': (-1.5,1.5)},
    {'name': 'x2', 'type': 'continuous', 'domain': (-1.5,1.5)},
]

# Definition of fixed environment parameter
environment = [
    {'name': 'radius', 'type': 'fixed', 'domain': 1.5},
]

# Definition of a constraint on the search domain
constraints = [
    {'name': 'circle', 'expression': 'sqrt(x1^2 + x2^2) <= radius'}
]

#Creation of studies to benchmark against each other
studies: dict[str, Study] = {}
drivers: list[str] = ["BayesianOptimization", "ActiveLearning", "CMAES", "DifferentialEvolution", "ScipyMinimizer"]
for driver in drivers:
    studies[driver] = client.create_study(
        design_space=design_space,
        environment=environment,
        constraints=constraints,
        driver=driver,
        name=driver,
        study_id=f"benchmark_{driver}",
        open_browser=False
    )

#Configuration of all studies
config_kwargs = dict(max_iter=250, num_parallel=2)
min_val = 1e-3 #Stop study when this value was observed
for driver, study in studies.items():
    if driver=="ActiveLearning":
        study.configure(
            surrogates=[dict(type="NN")],
            objectives=[dict(type="Minimizer", min_val=min_val)],
            **config_kwargs
        )
    elif driver=="ScipyMinimizer":
        #For a more global search, 3 initial gradient-free Nelder-Mead are started
        study.configure(method="Nelder-Mead", num_initial=3,
                        min_val=min_val, **config_kwargs)
    else:
        study.configure(min_val=min_val, **config_kwargs)
```

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

### Example Minimization and Constraint Objectives

Source: https://optimizer.jcmwave.com/documentation/python/2.0.5/_sources/drivers/ActiveLearning.rst

This example demonstrates how to configure a list of objectives for an optimization task. It includes a 'Minimizer' objective to minimize a target variable and a 'Constrainer' objective to enforce bounds on another variable. These objectives are essential for defining the optimization goals.

```python
[
  {'type': 'Minimizer', 'variable': 'variable1', 'strategy': 'EI'},
  {'type': 'Constrainer', 'variable': 'variable2', 'lower_bound': 0.0, 'upper_bound': 1.5}
]
```

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

### Get New Suggestion for Evaluation

Source: https://optimizer.jcmwave.com/documentation/python/3.0.0/interface/index

Requests a new suggestion from the study for the next evaluation. This method is central to the optimization loop, providing the parameters for the next observation. It can optionally take environment values to guide the suggestion.

```python
def evaluate(study: Study, x1: float, x2: float) -> Observation:
   obs = study.new_observation()
   obs.add(x1**2 + x2**2)
   return obs

suggestion = study.get_suggestion()
```

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

### Define Minimization and Outcome Constraint Objectives (MATLAB)

Source: https://optimizer.jcmwave.com/documentation/matlab/2.0.5/_sources/drivers/ActiveLearning.rst

Example demonstrating how to define a minimization objective and an outcome constraint using structs in MATLAB. These objectives are used to guide the active learning process by specifying what to minimize and what constraints to satisfy.

```matlab
struct('type', "Minimizer", 'variable', "variable1", 'strategy', "EI"),\
struct('type', "Constrainer", 'variable', "variable2", 'lower_bound', 0.0, 'upper_bound', 1.5)
```

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

### Setup and Benchmark Studies in MATLAB

Source: https://optimizer.jcmwave.com/documentation/matlab/2.1.3/tutorials/benchmark

This MATLAB script initializes the JCM Optimizer client, defines the search domain, environment, and constraints for optimization. It then creates multiple studies, each configured with a different driver (e.g., BayesianOptimization, CMAES). Finally, it sets up a benchmark to run these studies concurrently and compares their performance.

```matlab
1jcm_optimizer_path = '<JCM_OPTIMIZER_PATH>';
  addpath(fullfile(jcm_optimizer_path, 'interface', 'matlab'));
  
  server = jcmoptimizer.Server();
  client = jcmoptimizer.Client(server.host);
  
  % Definition of the search domain
  design_space = {
    struct('name', 'x1', 'type', 'continuous', 'domain', [-1.5,1.5]), 
    struct('name', 'x2', 'type', 'continuous', 'domain', [-1.5,1.5]), 
  };
  
  % Definition of fixed environment parameter
  environment = {
    struct('name', 'radius', 'type', 'fixed', 'domain', 1.5) 
  };
  
  % Definition of a constraint on the search domain
  constraints = {
    struct('name', 'circle', 'expression', 'sqrt(x1^2 + x2^2) <= radius')
  };
  
  %Creation of studies to benchmark against each other
  studies = struct();
  drivers = {"BayesianOptimization", "ActiveLearning", "CMAES", ...
            "DifferentialEvolution", "ScipyMinimizer"};
  for i = 1:length(drivers)
     studies.(drivers{i}) = client.create_study( ...
          'design_space', design_space, ...
          'environment', environment, ...
          'constraints', constraints, ...
          'driver', drivers{i}, ...
          'name', drivers{i}, ...
          'study_id', sprintf("benchmark_%s", drivers{i}), ...
          'open_browser' , false ...
     );
  end
  
  %Configuration of all studies
  config = {'num_parallel', 1, 'max_iter', 250};
  min_val = 1e-3; %Stop study when this value was observed
  for i = 1:length(drivers)
     driver = drivers{i};
     study = studies.(driver);
     if strcmp(driver, "ActiveLearning")
         study.configure( ...
            'surrogates', {struct('type', "NN")}, ...
            'objectives', {struct('type', "Minimizer", 'min_val', min_val)},
            config{:});
     elseif strcmp(driver, "ScipyMinimizer")
         %For a more global search, 3 initial gradient-free Nelder-Mead are started
         study.configure( ...
            'method', "Nelder-Mead", 'num_initial', 3, ...
            'min_val', min_val, config{:});
     else
         study.configure('min_val', min_val, config{:});
     end
  end
  
  % Creation of a benchmark with 6 repetitions and add all 4 studies
  benchmark = client.create_benchmark('num_average', 6);
  for i = 1:length(drivers)
     benchmark.add_study(studies.(drivers{i}));
  end
  
  % Run the benchmark - this will take a while
  benchmark.set_evaluator(@evaluate);
  benchmark.run();
  
  % Plot cummin convergence w.r.t. number of evaluations and time
  fig = figure('Position', [0, 0, 1000, 500]);
  subplot(1, 2, 1) 
  data = benchmark.get_data('x_type', "num_evaluations");

```

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

### Attempt to Start JCMoptimizer Server Process (Python)

Source: https://optimizer.jcmwave.com/documentation/python/3.0.0/_modules/jcmoptimizer/server

This snippet details the core logic for launching the JCMoptimizer executable. It configures the environment, constructs the command-line arguments, and uses `Popen` to start the process, redirecting stdout and stderr to temporary files for monitoring. It includes logic to detect immediate errors or successful port information.

```python
def _try_start_server(
    self,
    jcmoptimizer_exe: str,
    license_dir: Optional[str],
    persistent: bool,
    timeout: float,
    port: Optional[int],
) -> None:

    # get clean environment
    env = os.environ.copy()
    env.pop("PYTHONDEVMODE", None)
    if license_dir is not None:
        env["JCM_LICENSE_DIR"] = license_dir

    # Start JCMoptimizer
    cmd: list[str] = [f'"{jcmoptimizer_exe}"']
    if port is not None:
        cmd.append(f"--port {port}")
    cmd.append("--print_json")
    if not persistent:
        cmd.append(f"--calling_pid {os.getpid()}")
    close_fds = os.name != "nt"

    # Generate temporary files for errors and log
    with (
        tempfile.TemporaryFile() as error_file,
        tempfile.TemporaryFile() as log_file,
    ):
        Popen(
            " ".join(cmd),
            shell=True,
            stdout=log_file,
            stderr=error_file,
            close_fds=close_fds,
            universal_newlines=True,
            bufsize=1,
            start_new_session=True,
            env=env,
        )

        # Poll process for new output until first line with port information
        line = b""
        for _ in range(round(10 * timeout)):
            error_file.seek(0)
            if len(error_file.readlines()):
                response = _server_response(log_file, error_file)
                raise EnvironmentError(
                    "Could not start optimization server. "
                    f"Server response: \n{response}"
                )

            log_file.seek(0)
            for line in iter(log_file.readline, b""):
                if line[:17] == b'{"optimizer_port"':
                    break
            else:
                time.sleep(0.1)
                continue
            break
        else:
            response = _server_response(log_file, error_file)
            raise TimeoutError(response)
        try:
            info = json.loads(line)
        except Exception as err:
            response = _server_response(log_file, error_file)
            raise EnvironmentError(
                "Could not start optimization server. "
                f"Server response: \n{response}"
            ) from err

    self._port = int(info["optimizer_port"])
    self._pid = int(info["pid"])
```

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

### Configure JCMoptimizer Cloud Token

Source: https://optimizer.jcmwave.com/documentation/matlab/3.0.0/_sources/installation/index.rst

This YAML configuration snippet shows how to store your JCMoptimizer cloud access token in the global configuration file. The token is essential for authenticating with the JCMoptimizer cloud services. Replace '<my token string>' with your actual token.

```yaml
token: <my token string>
```

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

### Create Benchmark for Optimization Studies

Source: https://optimizer.jcmwave.com/documentation/python/2.0.5/interface/index

The create_benchmark method within the Client class is used to set up a benchmarking process for comparing different optimization studies. It allows specifying the number of averages for performance evaluation and whether to remove completed studies.

```python
from jcmoptimizer import Client

client = Client(host="http://localhost:4554")

# Create a benchmark object
benchmark = client.create_benchmark(num_average=6, remove_completed_studies=False)
```

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

### Add Matlab Directory to Path

Source: https://optimizer.jcmwave.com/documentation/matlab/3.0.0/_sources/installation/index.rst

This command adds the JCMoptimizer Matlab package directory to the Matlab search path. Ensure the path is correctly specified to allow Matlab to find the necessary functions. This can be done directly in scripts or via the Matlab startup file.

```matlab
addpath("~/jcmoptimizer/matlab/");
```

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

### Cloud Server Initialization Options

Source: https://optimizer.jcmwave.com/documentation/python/3.0.0/_modules/jcmoptimizer/server

When initializing a server for cloud deployment, specific arguments are available. These include setting a unique server ID, a descriptive name, a scheduled shutdown time, an API access token, and the cloud API endpoint URL. The version of the cloud optimizer can also be specified.

```python
import datetime as dt

server = Server(
    server_location='cloud',
    server_id="my_server",
    server_name="My Optimization Server",
    shutdown_at=dt.datetime.now() + dt.timedelta(hours=3),
    token="YOUR_API_TOKEN",
    cloud_endpoint="https://api.jcmwave.com",
    version="3.0.0"
)
```