Metadata-Version: 2.4
Name: jcmoptimizer
Version: 3.2.0
Summary: The JCMoptimizer interface for Python
Author-email: Philipp Schneider <philipp.schneider@jcmwave.com>
License-Expression: MIT
Project-URL: homepage, https://optimizer.jcmwave.com
Project-URL: documentation, https://optimizer.jcmwave.com/documentation/python/latest/interface/index.html
Project-URL: releasenotes, https://optimizer.jcmwave.com/release-notes
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.28.1
Requires-Dist: certifi>=2026.10.19
Requires-Dist: idna>=3.20
Requires-Dist: colorama
Dynamic: license-file

# JCMoptimizer Python Client #

This package implements a python client for interacting with the JCMoptimizer server. It provides a convenient interface to set up, run, and analyze numerical studies of expensive black box functions.

## Getting Started

### Cloud Service
The easiest way to get started is to use the free tier of the JCMwave's cloud service for JCMoptimizer:
* Install the `jcmoptimizer` package into your python environment, e.g. by running `pip install jcmoptimizer`.
* Signup to [optimizer.jcmwave.com](https://optimizer.jcmwave.com).
* Create an [API access token](https://optimizer.jcmwave.com/cloud/tokens/list/)

### Run JCMoptimizer Locally
For a self-hosted version, you need install JCMsuite and the JCMoptimizer extension for JCMsuite:
* Browse to the [JCMsuite download](https://installation.jcmwave.com/fb13885794fc64c42531c9656f8f6f73.php) page to install JCMsuite and to retrieve a demo or commercial license.
* Browse to the [JCMoptimizer download](https://optimizer.jcmwave.com/download) page to install JCMoptimizer.

### Local Package Installation and Shared Configuration

The Python interface bundled with a local installation can be installed directly
into your chosen environment, with the matching version and dependencies:

```bash
python -m pip install /path/to/JCMoptimizer/interface/python/jcmoptimizer
```

On Windows, quote the installation directory when it contains spaces. The shared
installation can be read-only; build output is placed in temporary directories.
This installs the client, not the optimizer server. Dependency/build-tool downloads
require access to a package index or a suitable local wheelhouse.

For site-wide defaults without administrator rights, set `JCMOPTIMIZER_CONFIG` to
an existing YAML configuration file, for example:

```bash
export JCMOPTIMIZER_CONFIG=/shared/software/config/jcmoptimizer.yml
```

```powershell
$env:JCMOPTIMIZER_CONFIG = 'Z:\software\config\jcmoptimizer.yml'
```

Its settings are overridden by `~/.jcmoptimizer.conf.yml`, then by
`.jcmoptimizer.conf.yml` in the current working directory, and finally by explicit
Python arguments. An unset/empty variable adds no file; a selected file that is
missing, unreadable or malformed raises an error. Keep personal tokens in the home
file. A shared local setup can contain:

```yaml
server_location: local
jcmoptimizer_dir: /shared/software/JCMoptimizer
license_dir: /shared/software/JCMsuite/license
```

### First Example
A basic usage example of the python package is given in the tutorial on a [Bayesian Optimization](https://optimizer.jcmwave.com/documentation/python/latest/tutorials/vanilla_bayesian_optimization.html).

## Documentation

### Synchronous and asynchronous clients

Remote methods use one implementation and one method reference. Calls block by
default; `Client(asynchronous=True)` returns coroutines for remote operations.
Its constructor does no network I/O. Context entry or the first awaited operation
connects or starts the configured server without an explicit `Server` instance:

```python
async with Client(asynchronous=True) as client:
    study = await client.create_study(design_space=design_space, open_browser=False)
    await study.configure(max_iter=20, num_parallel=2)
    study.set_evaluator(evaluate)
    await study.run()
    minimum = await study.driver.get_min_objective()
    best = await study.driver.get_best_sample()
```

The mode propagates to studies, benchmarks and drivers. Local operations such as
`set_evaluator`, `new_observation`, and observation editing remain regular calls.
In blocking code, `with Client() as client:` and `driver.min_objective` still work.
Network-backed properties require their `get_*()` method in async mode. Generated
typing declarations select the result or coroutine from the client mode; regenerate
them with `python tools/generate_typing.py` after changing coroutine signatures.

Async clients and their handles belong to one event loop. Use an async context or
`await client.close()` for cleanup; async destructors do not perform I/O. Closing
releases remote handles and HTTP connections, cancels active operations and stops
an owned nonpersistent server. Supplied hosts and reused cloud servers remain
running. `persistent=True` also preserves a newly started server. Explicit
`await client.shutdown_server()` can stop a borrowed server when intended.
Clients, studies and benchmarks all use `close()` in synchronous mode and
`await close()` in asynchronous mode.
Standalone synchronous `Server` remains available; no async server class is needed.

HTTP requests use pooled native HTTPX coroutines with no execution/read timeout.
Synchronous clients use a single background I/O loop, rather than a worker per
request. Async evaluator functions run on the caller loop; synchronous evaluators
run in a dedicated thread pool and must be thread-safe. Server `num_parallel`
controls evaluation concurrency. Both modes use `study.run()`; `run_async()` was
removed before the 3.2.0 release.

Evaluator failures are logged and tolerated until `study.max_num_failed`
consecutive failures (default: 3), at which point the last error propagates.
Successful observation submission resets the failure count. Request and upload
errors propagate immediately.

Ctrl-C in blocking `run()`, or cancellation of async `run()`, cancels evaluations,
clears owned suggestions and stops the study. In-flight mutations settle before
cleanup, so an unresponsive server can delay cancellation. Python worker threads
cannot be forcibly cancelled and may delay interpreter exit. Observations and
continuation settings are preserved. Closing the client then applies server
ownership rules. Benchmarks use the same mode and require studies from that client.

For a comprehensive overview of all available classes, methods, and their parameters, please refer to the official JCMoptimizer Python documentation:

*   [JCMoptimizer Python Interface Documentation](https://optimizer.jcmwave.com/documentation/python/latest/interface/index.html)
*   [JCMoptimizer Python Tutorials](https://optimizer.jcmwave.com/documentation/python/latest/tutorials/index.html)

These resources provide detailed explanations and examples for advanced usage, including different drivers.
