### Install HGDL Library

Source: https://github.com/lbl-camera/hgdl/blob/master/examples/schwefel_constrained.ipynb

Installs the HGDL library version 2.1.9. This is a prerequisite for running the optimization scripts.

```python
#!pip install hgdl==2.1.9
```

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

### Start Asynchronous Optimization

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Launches the distributed optimization process. This method is non-blocking and returns immediately, allowing the main thread to perform other tasks or poll for results. Optionally accepts a Dask client for HPC usage and initial starting positions.

```python
import numpy as np
import dask.distributed as distributed
from hgdl.hgdl import HGDL
from hgdl.support_functions import schwefel, schwefel_gradient

bounds = np.array([[-500.0, 500.0],
                   [-500.0, 500.0]])

optimizer = HGDL(
    schwefel,
    schwefel_gradient,
    bounds,
    global_optimizer="genetic",
    local_optimizer="dNewton",
    number_of_optima=30000,
    num_epochs=100
)

# Optional: connect to a remote Dask scheduler for multi-node HPC usage
# client = distributed.Client("scheduler-address:8786")
# optimizer.optimize(dask_client=client, x0=x0)

# Provide initial walker positions; shape (N_walkers, D)
x0 = np.random.uniform(low=bounds[:, 0], high=bounds[:, 1], size=(20, 2))

# Non-blocking: returns immediately; optimization runs in background
optimizer.optimize(x0=x0, tolerance=1e-10)

# Main thread is now free; query results asynchronously
import time
time.sleep(5)
print("Current best optima:", optimizer.get_latest()[:3])
```

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

### HGDL API Usage Example

Source: https://github.com/lbl-camera/hgdl/blob/master/README.md

Demonstrates basic usage of the HGDL API for function optimization. Requires numpy, hgdl, and dask.distributed. Ensure the optimization function and its gradient are defined.

```python
import numpy as np
from hgdl.hgdl import HGDL as hgdl
from hgdl.support_functions import *
import dask.distributed as distributed

bounds = np.array([[-500,500],[-500,500]])
#dask_client = distributed.Client("10.0.0.184:8786")
a = hgdl(schwefel, schwefel_gradient, bounds,
        global_optimizer = "genetic",
        local_optimizer = "dNewton", #put in local optimzers from scipy.optimize.minimize
        number_of_optima = 30000,
        num_epochs = 100)

x0 = np.random.uniform(low = bounds[:, 0], high = bounds[:,1],size = (20,2))
a.optimize(x0 = x0)

###the thread is now released, but the work continues in the background

a.get_latest() ##prints the current result whenever queried

a.kill_client() ##stops the execution and returns the result
```

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

### Custom Global Optimizer with HGDL

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Implement a custom global optimizer by providing a callable to the `global_optimizer` argument. This function should accept elite population data and return new starting positions.

```python
import numpy as np
from hgdl.hgdl import HGDL
from hgdl.support_functions import schwefel, schwefel_gradient

def my_global_optimizer(positions, func_values, bounds, n_offspring):
    """
    A simple perturbation-based global step: take the best solution
    and scatter offspring around it with Gaussian noise.
    positions:   np.ndarray (N, D) – current elite positions
    func_values: np.ndarray (N,)   – corresponding f(x) values
    bounds:      np.ndarray (D, 2) – domain bounds
    n_offspring: int               – number of new points to return
    Returns: np.ndarray (n_offspring, D)
    """
    best_idx = np.argmin(func_values)
    best = positions[best_idx]
    scale = (bounds[:, 1] - bounds[:, 0]) * 0.05  # 5% of domain width
    offspring = best + np.random.normal(0, scale, size=(n_offspring, len(best)))
    # Clip to bounds
    offspring = np.clip(offspring, bounds[:, 0], bounds[:, 1])
    return offspring

bounds = np.array([[-500.0, 500.0], [-500.0, 500.0]])
optimizer = HGDL(schwefel, schwefel_gradient, bounds,
                 global_optimizer=my_global_optimizer,  # custom callable
                 local_optimizer="L-BFGS-B",
                 num_epochs=50)

x0 = np.random.uniform(low=bounds[:, 0], high=bounds[:, 1], size=(10, 2))
optimizer.optimize(x0=x0)

import time; time.sleep(8)
results = optimizer.kill_client()
print(f"Found {len(results)} optima with custom global optimizer")
```

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

### Terminate optimization and shut down Dask client

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Use `kill_client` to cancel all ongoing tasks and shut down the Dask client, releasing all cluster resources. This method returns the final list of optima found before termination and is the recommended way to cleanly end an HGDL run. Ensure the optimizer is configured with appropriate parameters like `number_of_optima` and `num_epochs` before starting the optimization.

```python
import time
from hgdl.hgdl import HGDL
from hgdl.support_functions import schwefel, schwefel_gradient
import numpy as np

bounds = np.array([[-500.0, 500.0], [-500.0, 500.0]])
optimizer = HGDL(schwefel, schwefel_gradient, bounds,
                 global_optimizer="genetic",
                 local_optimizer="dNewton",
                 number_of_optima=5000,
                 num_epochs=10000)

x0 = np.random.uniform(low=bounds[:, 0], high=bounds[:, 1], size=(20, 2))
optimizer.optimize(x0=x0)

time.sleep(15)

# Terminate and release all resources; returns final optima list
final = optimizer.kill_client()

print(f"Total optima found: {len(final)}")
print("Top 3 minima:")
minima = [e for e in final if e["classifier"] == "minimum"][:3]
for m in minima:
    print(f"  x={m['x']}, f(x)={m['f(x)']:.6f}")
```

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

### Stop optimization tasks and get partial results

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Call `cancel_tasks` to signal all running epoch tasks to stop and cancel their Dask futures. This method returns the current list of optima found up to the cancellation point, while keeping the Dask client alive for potential reuse. A `time.sleep` is often used before cancellation to allow some computation to occur.

```python
import time

optimizer.optimize(x0=x0)
time.sleep(8)

# Stop computation without closing the Dask client
partial_results = optimizer.cancel_tasks()

print(f"Stopped after partial run; found {len(partial_results)} optima")
for entry in partial_results[:3]:
    print(f"  x={entry['x']}, f(x)={entry['f(x)']:.4f}, type={entry['classifier']}")
```

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

### Initialize and Run HGDL Constrained Optimization

Source: https://github.com/lbl-camera/hgdl/blob/master/examples/schwefel_constrained.ipynb

Imports HGDL, defines optimization parameters, sets up constraints using scipy.optimize.NonlinearConstraint, and then initializes and runs the HGDL optimizer. The local optimizer defaults to 'SLSQP' due to the presence of constraints.

```python
from hgdl.hgdl import HGDL as hgdl
from hgdl.support_functions import *
import time

#example arguments that will be passed to the function, the gradient and the Hessian function
a  = 5
b  = 6

#constraint definitions form scipy
from scipy.optimize import NonlinearConstraint
nlc = NonlinearConstraint(g1, -np.inf, 0)
nlc = NonlinearConstraint(g2, 0,np.inf)


a = hgdl(schwefel, schwefel_gradient, bounds,
            hess = None, ##if this is None, the Hessian will be approximated if the local optimizer needs it
            global_optimizer = "random", #there are a few options to choose from for the global optimizer
            #global_optimizer = "genetic",
            local_optimizer = "dNewton", #dNewton is an example and will be changed automatically to "SLSQP" because constraints are used
            number_of_optima = 30000, #the number fo optima that will be stored and used for deflation
            args = (a,b), num_epochs = 1000, #the number of total epochs. Since this is an asynchronous algorithms, this number can be very high 
            constraints = (nlc,) #the constraints
            )
    
a.optimize(x0=None)
```

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

### Initialize and Run HGDL Optimizer

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Sets up the HGDL optimizer with specified objective and gradient functions, bounds, and optimization parameters. It then runs the optimization process using a Dask client and a set of initial points, periodically polling for the latest results.

```python
def schwefel_4d(x, *args):
    return 418.9829 * len(x) - np.sum(x * np.sin(np.sqrt(np.abs(x))))

def schwefel_4d_grad(x, *args):
    x = np.where(x == 0, 1e-4, x)
    return -(np.sin(np.sqrt(np.abs(x))) + 
             x * np.cos(np.sqrt(np.abs(x))) * 0.5 / np.sqrt(np.abs(x)) * np.sign(x))

optimizer = HGDL(schwefel_4d, schwefel_4d_grad, bounds,
                 global_optimizer="genetic",
                 local_optimizer="L-BFGS-B",
                 number_of_optima=100000,
                 num_epochs=500)

x0 = np.random.uniform(low=bounds[:, 0], high=bounds[:, 1], size=(30, 4))
optimizer.optimize(dask_client=client, x0=x0, tolerance=1e-8)
```

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

### Initialize HGDL Optimizer

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Constructs an HGDL optimizer instance. Specify the objective function, its gradient and Hessian, domain bounds, and tuning parameters. Supports nonlinear constraints, which forces the local optimizer to SLSQP.

```python
import numpy as np
from hgdl.hgdl import HGDL
from scipy.optimize import rosen, rosen_der, rosen_hess
from scipy.optimize import NonlinearConstraint

# Define a nonlinear constraint: ||x||^2 / 10 <= 2
def g1(x):
    return (np.linalg.norm(x) ** 2 / 10.0) - 2.0

nlc = NonlinearConstraint(g1, -np.inf, 0)

bounds = np.array([[-2.0, 2.0],
                   [-2.0, 2.0]])

optimizer = HGDL(
    func=rosen,               # Objective to MINIMIZE (callable: x -> scalar)
    grad=rosen_der,           # Gradient (callable: x -> array of shape (D,)))
    bounds=bounds,            # Domain bounds, shape (D, 2)
    hess=rosen_hess,          # Optional Hessian (callable: x -> array (D, D))
    global_optimizer="random",# "genetic" (default), "random", or custom callable
    local_optimizer="dNewton",# "dNewton", "L-BFGS-B", "BFGS", "CG", "SLSQP", etc.
    number_of_optima=30000,   # Max optima retained in the result list
    num_epochs=1000,          # Max epochs before termination
    args=(),                  # Extra args passed to func, grad, hess
    constraints=(nlc,)        # scipy NonlinearConstraint objects; forces SLSQP
)
# optimizer.optima.list is [] at this point; call optimize() to start
```

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

### HGDL.__init__

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Constructs an HGDL optimizer instance by specifying the objective function, its gradient (and optionally its Hessian), the domain bounds, and tuning parameters for the global/local sub-algorithms.

```APIDOC
## `HGDL.__init__` — Construct an HGDL optimizer

### Description
Creates an HGDL optimizer instance by specifying the objective function, its gradient (and optionally its Hessian), the domain bounds, and tuning parameters for the global/local sub-algorithms. The constructor validates inputs, sets up the optima store, and selects the local optimizer (automatically switching to `SLSQP` if constraints are provided).

### Method
```python
__init__(self, func, grad, bounds, hess=None, global_optimizer='genetic', local_optimizer='dNewton', number_of_optima=30000, num_epochs=1000, args=(), constraints=None)
```

### Parameters
- **func** (callable) - The objective function to minimize.
- **grad** (callable) - The gradient of the objective function.
- **bounds** (numpy.ndarray) - Domain bounds with shape (D, 2).
- **hess** (callable, optional) - The Hessian of the objective function. Defaults to None.
- **global_optimizer** (str or callable, optional) - The global optimization strategy. Can be 'genetic', 'random', or a custom callable. Defaults to 'genetic'.
- **local_optimizer** (str, optional) - The local optimization algorithm. Options include 'dNewton', 'L-BFGS-B', 'BFGS', 'CG', 'SLSQP', etc. Defaults to 'dNewton'.
- **number_of_optima** (int, optional) - The maximum number of optima to retain in the result list. Defaults to 30000.
- **num_epochs** (int, optional) - The maximum number of epochs before termination. Defaults to 1000.
- **args** (tuple, optional) - Extra arguments to be passed to func, grad, and hess. Defaults to ().
- **constraints** (tuple of scipy.optimize.NonlinearConstraint, optional) - Constraints for the optimization. If provided, forces the local optimizer to 'SLSQP'. Defaults to None.

### Request Example
```python
import numpy as np
from hgdl.hgdl import HGDL
from scipy.optimize import rosen, rosen_der, rosen_hess
from scipy.optimize import NonlinearConstraint

# Define a nonlinear constraint: ||x||^2 / 10 <= 2
def g1(x):
    return (np.linalg.norm(x) ** 2 / 10.0) - 2.0

nlc = NonlinearConstraint(g1, -np.inf, 0)

bounds = np.array([[-2.0, 2.0],
                   [-2.0, 2.0]])

optimizer = HGDL(
    func=rosen,               # Objective to MINIMIZE (callable: x -> scalar)
    grad=rosen_der,           # Gradient (callable: x -> array of shape (D,)))
    bounds=bounds,            # Domain bounds, shape (D, 2)
    hess=rosen_hess,          # Optional Hessian (callable: x -> array (D, D))
    global_optimizer="random",# "genetic" (default), "random", or custom callable
    local_optimizer="dNewton",# "dNewton", "L-BFGS-B", "BFGS", "CG", "SLSQP", etc.
    number_of_optima=30000,   # Max optima retained in the result list
    num_epochs=1000,          # Max epochs before termination
    args=(),                  # Extra args passed to func, grad, hess
    constraints=(nlc,)        # scipy NonlinearConstraint objects; forces SLSQP
)
```
```

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

### Initialize and Run HGDL Constrained Optimization

Source: https://github.com/lbl-camera/hgdl/blob/master/examples/rosenbrock_constrained.ipynb

Imports necessary HGDL components and SciPy optimization functions. Initializes HGDL with Rosenbrock's function, its derivatives, bounds, and a nonlinear constraint. It then runs the optimization process.

```python
from hgdl.hgdl import HGDL as hgdl
from hgdl.support_functions import *
import time
from scipy.optimize import rosen, rosen_der, rosen_hess


#constraint definitions form scipy
from scipy.optimize import NonlinearConstraint
nlc = NonlinearConstraint(g1, 0, 10)


a = hgdl(rosen, rosen_der, bounds,
            hess = rosen_hess, ##if this is None, the Hessian will be approximated if the local optimizer needs it
            #global_optimizer = "random", #there are a few options to choose from for the global optimizer
            global_optimizer = "genetic",
            local_optimizer = "L-BFGS-B", #dNewton is an example and will be changed automatically to "SLSQP" because constraints are used
            number_of_optima = 30000, #the number fo optima that will be stored and used for deflation
            args = (), num_epochs = 1000, #the number fo total epochs. Since this is an asynchronous algorithms, this number can be very high 
            constraints = (nlc,) #the constraints
            #constraints = () #if no constraints are used
            )
    
a.optimize(x0=None)
```

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

### Iterate through optimization results

Source: https://context7.com/lbl-camera/hgdl/llms.txt

This snippet shows how to iterate through a list of optimization results, printing key information for each entry. It is useful for inspecting the output of optimization runs.

```python
# Example output:
# x=[ 420.9687  420.9687], f(x)=0.000001, type=minimum
# x=[-302.5219  420.9687], f(x)=837.9658, type=minimum
```

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

### Enable HGDL Logging

Source: https://github.com/lbl-camera/hgdl/blob/master/docs/source/api/logging.md

To enable logging specifically for the 'hgdl' module, import the logger and call the enable method.

```python
from loguru import logger
logger.enable("hgdl")
```

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

### Log to File

Source: https://github.com/lbl-camera/hgdl/blob/master/docs/source/api/logging.md

Configure Loguru to write log messages to a file. The filename can include time-based formatting.

```python
logger.add("file_{time}.log")
```

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

### Define Bounds and Constraints for Optimization

Source: https://github.com/lbl-camera/hgdl/blob/master/examples/schwefel_constrained.ipynb

Sets up the search space bounds and defines two constraint functions, g1 and g2, for the optimization problem. These are used by scipy.optimize.minimize.

```python
bounds = np.array([[-500,500],[-500,500]])
def g1(x):
    return (np.linalg.norm(x)**2/10.0) - 16000.0
def g2(x):
    return (np.linalg.norm(x)**2/10.0) - 4000.0
```

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

### Plotting Functions for Optimization Visualization

Source: https://github.com/lbl-camera/hgdl/blob/master/examples/rosenbrock_constrained.ipynb

Provides functions to create 3D surface plots and scatter plots for visualizing optimization results and constraints. Requires numpy and plotly.

```python
%load_ext autoreload
%autoreload 2
import numpy as np
import plotly.graph_objects as go
def plot(x,y,z,data = None, constr = None):
    fig = go.Figure()
    fig.add_trace(go.Surface(x = x, y = y,z=z))
    if data is not None: 
        fig.add_trace(go.Scatter3d(x=data[:,0], y=data[:,1], z=data[:,2] + 50,
                                   mode='markers'))
    if constr is not None:
        fig.add_trace(go.Scatter3d(x=constr[:,0], y=constr[:,1], z=constr[:,2],
                                   mode='markers')) 

    fig.update_layout(title='Surface Plot', autosize=True,
                  width=800, height=800, font=dict(
                  family="Courier New, monospace",
                  size=18),
                  margin=dict(l=65, r=50, b=65, t=90))

    fig.show()

def make_plot(bounds, function, data = None, constraint = None):
    x1,x2 = np.linspace(bounds[0,0],bounds[0,1],100),np.linspace(bounds[1,0],bounds[1,1],100)
    x_pred = np.transpose([np.tile(x1, len(x2)), np.repeat(x2, len(x1))])
    x1,x2 = np.meshgrid(x1,x2)
    z = np.zeros((10000))
    func = np.zeros((10000))
    cons = np.zeros((10000))
    for i in range(10000): 
        z[i] = rosen(x_pred[i])
        if constraint: cons[i] = constraint(x_pred[i])

    
    plot(x1, x2, z.reshape(100,100).T, data = data)

    if constraint:
        fig = go.Figure()
        fig.add_trace(go.Surface(x = x1, y = x2,z = cons.reshape(100,100).T))
        fig.show()
```

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

### Retrieve and Print Optimization Results

Source: https://github.com/lbl-camera/hgdl/blob/master/examples/schwefel_constrained.ipynb

Fetches the latest optimization results from the HGDL object and prints each entry. This allows inspection of the found optima and their corresponding function values.

```python
res = a.get_latest()
for entry in res: print(entry)
```

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

### Visualize Optimization Results with Constraints

Source: https://github.com/lbl-camera/hgdl/blob/master/examples/schwefel_constrained.ipynb

Generates a plot showing the Schwefel function surface, the defined constraints, and the optima found by HGDL. The found points should lie between the two constraint boundaries.

```python
data = [np.append(entry["x"],entry["f(x)"]) for entry in res]
make_plot(data = np.array(data), constraint1 = g1, constraint2 = g2)
```

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

### Plotting Utilities for Optimization Results

Source: https://github.com/lbl-camera/hgdl/blob/master/examples/schwefel_constrained.ipynb

Provides functions to create 3D surface plots for visualizing the objective function and scatter plots for data points and constraints. Requires numpy and plotly.

```python
%load_ext autoreload
%autoreload 2
import numpy as np
import plotly.graph_objects as go
def plot(x,y,z,data = None, constr = None):
    fig = go.Figure()
    fig.add_trace(go.Surface(x = x, y = y,z=z))
    if data is not None: 
        fig.add_trace(go.Scatter3d(x=data[:,0], y=data[:,1], z=data[:,2] + 50,
                                   mode='markers'))
    if constr is not None:
        fig.add_trace(go.Scatter3d(x=constr[:,0], y=constr[:,1], z=constr[:,2],
                                   mode='markers')) 

    fig.update_layout(title='Surface Plot', autosize=True,
                  width=800, height=800, font=dict(
                  family="Courier New, monospace",
                  size=18),
                  margin=dict(l=65, r=50, b=65, t=90))

    fig.show()

def make_plot(data = None, constraint1 = None, constraint2 = None):
    x1,x2 = np.linspace(-500,500,100),np.linspace(-500,500,100)
    x_pred = np.transpose([np.tile(x1, len(x2)), np.repeat(x2, len(x1))])
    r1 = np.sqrt(160000.)
    r2 = np.sqrt(40000.)
    c1,c2 = r1*np.cos(np.linspace(0,2.*np.pi,100)),r1*np.sin(np.linspace(0,2.*np.pi,100))
    d1,d2 = r2*np.cos(np.linspace(0,2.*np.pi,100)),r2*np.sin(np.linspace(0,2.*np.pi,100))
    c3 = np.zeros((len(c2)))
    d3 = np.zeros((len(c2)))
    x1,x2 = np.meshgrid(x1,x2)
    z = np.zeros((10000))
    zc1 = np.zeros((10000))
    zc2 = np.zeros((10000))
    for i in range(10000): 
        z[i] = schwefel(x_pred[i], 1, 1)
        if constraint1: zc1[i] = constraint1(x_pred[i])
        if constraint2: zc2[i] = constraint2(x_pred[i])
    for i in range(len(c1)):
        c3[i] = schwefel(np.array([c1[i],c2[i]]))
        d3[i] = schwefel(np.array([d1[i],d2[i]]))
    plot(x1,x2,z.reshape(100,100).T, data = data, 
         constr = np.row_stack([np.column_stack([c1,c2,c3]),np.column_stack([d1,d2,d3])]))
```

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

### HGDL.optimize

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Launches the distributed optimization across the Dask cluster. The method returns immediately (non-blocking); the algorithm continues running in the background.

```APIDOC
## `HGDL.optimize` — Start asynchronous optimization

### Description
Launches the distributed optimization across the Dask cluster. The method returns immediately (non-blocking); the algorithm continues running in the background. Optionally accepts a Dask client for HPC cluster usage and a set of initial starting positions.

### Method
```python
optimize(self, x0=None, dask_client=None, tolerance=1e-08)
```

### Parameters
- **x0** (numpy.ndarray, optional) - Initial walker positions with shape (N_walkers, D). Defaults to None.
- **dask_client** (dask.distributed.Client, optional) - A Dask client for HPC cluster usage. Defaults to None.
- **tolerance** (float, optional) - The tolerance for optimization convergence. Defaults to 1e-08.

### Request Example
```python
import numpy as np
import dask.distributed as distributed
from hgdl.hgdl import HGDL
from hgdl.support_functions import schwefel, schwefel_gradient

bounds = np.array([[-500.0, 500.0],
                   [-500.0, 500.0]])

optimizer = HGDL(
    schwefel,
    schwefel_gradient,
    bounds,
    global_optimizer="genetic",
    local_optimizer="dNewton",
    number_of_optima=30000,
    num_epochs=100
)

# Optional: connect to a remote Dask scheduler for multi-node HPC usage
# client = distributed.Client("scheduler-address:8786")
# optimizer.optimize(dask_client=client, x0=x0)

# Provide initial walker positions; shape (N_walkers, D)
x0 = np.random.uniform(low=bounds[:, 0], high=bounds[:, 1], size=(20, 2))

# Non-blocking: returns immediately; optimization runs in background
optimizer.optimize(x0=x0, tolerance=1e-10)

# Main thread is now free; query results asynchronously
import time
time.sleep(5)
print("Current best optima:", optimizer.get_latest()[:3])
```
```

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

### Custom Local Optimizer with HGDL

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Integrate custom gradient-based local optimizers by passing a callable to `local_optimizer`. The callable must mirror the interface of `scipy.optimize.minimize`.

```python
import numpy as np
from scipy.optimize import minimize
from hgdl.hgdl import HGDL
from hgdl.support_functions import schwefel, schwefel_gradient

def my_local_optimizer(func, grad, hess, bounds, x0, *args):
    """
    Wraps scipy's Newton-CG with a custom iteration limit.
    Must return an object with attributes: x, fun, jac
    """
    result = minimize(func, x0, args=args, method="Newton-CG",
                      jac=grad, hess=hess,
                      options={"maxiter": 200, "disp": False})
    return result

bounds = np.array([[-500.0, 500.0], [-500.0, 500.0]])
optimizer = HGDL(schwefel, schwefel_gradient, bounds,
                 global_optimizer="genetic",
                 local_optimizer=my_local_optimizer,
                 num_epochs=30)

x0 = np.random.uniform(low=bounds[:, 0], high=bounds[:, 1], size=(8, 2))
optimizer.optimize(x0=x0)

import time; time.sleep(6)
results = optimizer.kill_client()
print(f"Custom local optimizer found {len(results)} optima")
```

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

### Configuring Logging with Loguru in HGDL

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Enable and configure HGDL logging using Loguru. By default, logging is disabled. Use `logger.enable('hgdl')` to activate it and `logger.add()` to specify log destinations and levels.

```python
import sys
from loguru import logger

# Enable HGDL logging (disabled by default)
logger.enable("hgdl")

# Log DEBUG and above to stderr, filtered to hgdl namespace
logger.add(sys.stderr, filter="hgdl", level="DEBUG")

# Log to a rotating file for long HPC runs
logger.add("hgdl_run_{time}.log", filter="hgdl", level="INFO",
           rotation="100 MB", retention="7 days")

# Now instantiate and run as normal; logs will appear
from hgdl.hgdl import HGDL
from hgdl.support_functions import schwefel, schwefel_gradient
import numpy as np

bounds = np.array([[-500.0, 500.0], [-500.0, 500.0]])
optimizer = HGDL(schwefel, schwefel_gradient, bounds, num_epochs=5)
x0 = np.random.uniform(low=bounds[:, 0], high=bounds[:, 1], size=(6, 2))
optimizer.optimize(x0=x0)
results = optimizer.get_final()
# Logs will print epoch progress, worker assignments, and deflation events
```

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

### Configure Logging Level

Source: https://github.com/lbl-camera/hgdl/blob/master/docs/source/api/logging.md

Set the minimum logging level for messages from 'hgdl' to be displayed on standard error. Refer to Python's logging levels for details.

```python
import sys
logger.add(sys.stderr, filter="hgdl", level="INFO")
```

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

### Wait for all optimization epochs to complete

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Use `get_final` to block until all optimization epochs are finished or the process is cancelled. It returns the complete list of computed optima. Ensure the HGDL optimizer is initialized with the objective function, gradient, bounds, and desired optimizers.

```python
import numpy as np
from hgdl.hgdl import HGDL
from hgdl.support_functions import schwefel, schwefel_gradient

bounds = np.array([[-500.0, 500.0], [-500.0, 500.0]])
optimizer = HGDL(schwefel, schwefel_gradient, bounds,
                 global_optimizer="genetic",
                 local_optimizer="L-BFGS-B",
                 num_epochs=20)

x0 = np.random.uniform(low=bounds[:, 0], high=bounds[:, 1], size=(10, 2))
optimizer.optimize(x0=x0)

# Blocks until all 20 epochs finish
final_results = optimizer.get_final()

best = final_results[0]
print(f"Global minimum candidate: x={best['x']}, f(x)={best['f(x)']:.6f}")
print(f"Classification: {best['classifier']}")
print(f"Hessian eigenvalues: {best['Hessian eigvals']}")
# Output:
# Global minimum candidate: x=[420.968...  420.968...], f(x)=0.000000
# Classification: minimum
# Hessian eigenvalues: [0.7071 0.7071]
```

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

### Finalize Optimizer and Report Results

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Terminates the Dask client associated with the HGDL optimizer and prints the total number of unique optima discovered.

```python
final = optimizer.kill_client()
print(f"Finished: {len(final)} total unique optima discovered")
```

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

### Inspect Dask cluster worker topology

Source: https://context7.com/lbl-camera/hgdl/llms.txt

The `get_client_info` method provides details about the host and walker workers in the Dask cluster, which is useful for debugging connectivity issues. It returns a dictionary containing the host address and a list of walker addresses.

```python
optimizer.optimize(x0=x0)

info = optimizer.get_client_info()
print("Host worker:", info["host"])
print(f"Number of walker workers: {len(info['walkers'])}")
print("Walker addresses:", info["walkers"])
# Example output:
# Host worker: tcp://127.0.0.1:54321
# Number of walker workers: 3
# Walker addresses: ['tcp://127.0.0.1:54322', 'tcp://127.0.0.1:54323', 'tcp://127.0.0.1:54324']
```

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

### Generate Plot of Optimization Results with Constraints

Source: https://github.com/lbl-camera/hgdl/blob/master/examples/rosenbrock_constrained.ipynb

Creates a plot visualizing the optimization results. It overlays the found optima on the Rosenbrock function's surface, along with the defined constraints, to visually assess the optimization performance.

```python
data = [np.append(entry["x"],entry["f(x)"]) for entry in res]
make_plot(bounds, rosen, data = np.array(data), constraint = g1)
```

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

### HPC Dask Cluster Integration with HGDL

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Leverage a pre-deployed Dask distributed cluster for large-scale HGDL problems. Connect to the cluster using `distributed.Client` and pass the client to HGDL.

```python
import numpy as np
import dask.distributed as distributed
from hgdl.hgdl import HGDL
from hgdl.support_functions import schwefel, schwefel_gradient

# Connect to a pre-deployed Dask cluster (e.g., SLURM / PBS / Kubernetes)
client = distributed.Client("tcp://10.0.0.184:8786")
print(client)
# <Client: 'tcp://10.0.0.184:8786' processes=16 threads=16, memory=256.00 GiB>

bounds = np.array([[-500.0, 500.0]] * 4)  # 4-dimensional Schwefel
```

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

### Define Bounds and Constraint Function

Source: https://github.com/lbl-camera/hgdl/blob/master/examples/rosenbrock_constrained.ipynb

Sets the search space bounds and defines a constraint function for the optimization problem. The constraint function g1 checks if the squared norm of x divided by 10 is less than or equal to 1.

```python
bounds = np.array([[-4,4],[-4,4]])
def g1(x):
    return (np.linalg.norm(x)**2/10.0) - 1.0
```

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

### HGDL.get_client_info

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Retrieves and returns a dictionary containing information about the current Dask cluster's topology, including the host worker address and a list of walker worker addresses. This is useful for diagnosing cluster connectivity issues.

```APIDOC
## HGDL.get_client_info — Inspect distributed worker topology

Returns the dictionary describing the host worker and walker workers in the current Dask cluster, as seen by HGDL. Useful for debugging cluster connectivity.

### Example
```python
optimizer.optimize(x0=x0)

info = optimizer.get_client_info()
print("Host worker:", info["host"])
print(f"Number of walker workers: {len(info['walkers'])}")
print("Walker addresses:", info["walkers"])
```
```

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

### HGDL.get_latest

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Fetches the most recently computed snapshot of the optima list from the distributed Dask variable. Can be called at any time while `optimize()` is running.

```APIDOC
## `HGDL.get_latest` — Non-blocking result query

### Description
Fetches the most recently computed snapshot of the optima list from the distributed Dask variable. Can be called at any time while `optimize()` is running. Returns a list of dicts sorted by function value (ascending), each containing the position, function value, classifier, Hessian eigenvalues, gradient, and deflation radius.

### Method
```python
get_latest(self)
```

### Response
#### Success Response
- **optima_list** (list of dicts) - A list of dictionaries, sorted by function value (ascending). Each dictionary contains:
  - **x** (numpy.ndarray): The location of the optimum.
  - **fun** (float): The function value at the optimum.
  - **classifier** (str): Classification of the critical point (e.g., 'minimum', 'maximum', 'saddle point').
  - **eigenvalues** (numpy.ndarray): Eigenvalues of the Hessian matrix.
  - **gradient** (numpy.ndarray): The gradient vector at the optimum.
  - **deflation_radius** (float): The radius used for deflation.

### Response Example
```python
import time

# After optimizer.optimize() has been called:
time.sleep(3)

optima_list = optimizer.get_latest()

# Each entry in optima_list is a dict:
# {
#   "x":               np.ndarray of shape (D,),   # location
#   "fun":             float,                      # function value
#   "classifier":      str,                        # e.g. "minimum", "maximum", "saddle point"
#   "eigenvalues":     np.ndarray,                 # Hessian eigenvalues
#   "gradient":        np.ndarray,                 # gradient vector
#   "deflation_radius": float                       # deflation radius
# }
```
```

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

### Print Client Termination Status

Source: https://github.com/lbl-camera/hgdl/blob/master/examples/rosenbrock_constrained.ipynb

Prints the result of the HGDL client termination. This confirms whether the client was successfully shut down.

```python
print(res)
```

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

### HGDL.get_final

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Blocks the calling thread until all optimization epochs are completed and returns the final list of optima. This is useful when you need to ensure the entire optimization process has finished before proceeding.

```APIDOC
## HGDL.get_final — Blocking wait for all epochs

Blocks the calling thread until all `num_epochs` have completed (or the optimization is cancelled) and then returns the final, fully computed optima list. Use this when you want to wait for the algorithm to finish before proceeding.

### Example
```python
import numpy as np
from hgdl.hgdl import HGDL
from hgdl.support_functions import schwefel, schwefel_gradient

bounds = np.array([[-500.0, 500.0], [-500.0, 500.0]])
optimizer = HGDL(schwefel, schwefel_gradient, bounds,
                 global_optimizer="genetic",
                 local_optimizer="L-BFGS-B",
                 num_epochs=20)

x0 = np.random.uniform(low=bounds[:, 0], high=bounds[:, 1], size=(10, 2))
optimizer.optimize(x0=x0)

# Blocks until all 20 epochs finish
final_results = optimizer.get_final()

best = final_results[0]
print(f"Global minimum candidate: x={best['x']}, f(x)={best['f(x)']:.6f}")
print(f"Classification: {best['classifier']}")
print(f"Hessian eigenvalues: {best['Hessian eigvals']}")
```
```

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

### Fetch Latest Optimization Results

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Retrieves the most recent snapshot of the optima list from the Dask variable. This method is non-blocking and can be called at any time during optimization. The returned list is sorted by function value and contains detailed information for each optimum.

```python
import time

# After optimizer.optimize() has been called:
time.sleep(3)

optima_list = optimizer.get_latest()

# Each entry in optima_list is a dict:
# {
#   "x":               np.ndarray of shape (D,),   # location

```

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

### HGDL.kill_client

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Cancels all ongoing optimization tasks, shuts down the Dask client, and releases all associated cluster resources. This method returns the final list of optima found before termination and is the recommended way to cleanly end an HGDL run.

```APIDOC
## HGDL.kill_client — Stop optimization and shut down client

Cancels all tasks and closes the Dask client entirely, freeing all cluster resources. Returns the final optima list. This is the standard way to cleanly terminate an HGDL run.

### Example
```python
import time
from hgdl.hgdl import HGDL
from hgdl.support_functions import schwefel, schwefel_gradient
import numpy as np

bounds = np.array([[-500.0, 500.0], [-500.0, 500.0]])
optimizer = HGDL(schwefel, schwefel_gradient, bounds,
                 global_optimizer="genetic",
                 local_optimizer="dNewton",
                 number_of_optima=5000,
                 num_epochs=10000)

x0 = np.random.uniform(low=bounds[:, 0], high=bounds[:, 1], size=(20, 2))
optimizer.optimize(x0=x0)

time.sleep(15)

# Terminate and release all resources; returns final optima list
final = optimizer.kill_client()

print(f"Total optima found: {len(final)}")
print("Top 3 minima:")
minima = [e for e in final if e["classifier"] == "minimum"][:3]
for m in minima:
    print(f"  x={m['x']}, f(x)={m['f(x)']:.6f}")
```
```

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

### HGDL.cancel_tasks

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Signals all running epoch tasks to stop and cancels their Dask futures, but keeps the Dask client alive for potential reuse. It returns the current list of optima found at the time of cancellation.

```APIDOC
## HGDL.cancel_tasks — Stop optimization, keep client alive

Signals all running epoch tasks to stop (sets the distributed break condition) and cancels the Dask future, but leaves the Dask client running so it can be reused. Returns the current optima list at cancellation time.

### Example
```python
import time

optimizer.optimize(x0=x0)
time.sleep(8)

# Stop computation without closing the Dask client
partial_results = optimizer.cancel_tasks()

print(f"Stopped after partial run; found {len(partial_results)} optima")
for entry in partial_results[:3]:
    print(f"  x={entry['x']}, f(x)={entry['f(x)']:.4f}, type={entry['classifier']}")
```
```

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

### Poll Optimizer Progress

Source: https://context7.com/lbl-camera/hgdl/llms.txt

Periodically retrieves the latest optimization results from the HGDL optimizer. This is useful for monitoring progress in long-running tasks or interactive sessions.

```python
import time
for poll in range(5):
    time.sleep(10)
    snapshot = optimizer.get_latest()
    print(f"Poll {poll+1}: {len(snapshot)} optima found, best f(x)={snapshot[0]['f(x)']:.4f}")
```

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

### Terminate HGDL Client

Source: https://github.com/lbl-camera/hgdl/blob/master/examples/schwefel_constrained.ipynb

Cleans up and terminates the HGDL client process. This should be called after optimization is complete to free up resources.

```python
res = a.kill_client()
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.