Skip to main content

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:

Run JCMoptimizer Locally

For a self-hosted version, you need install JCMsuite and the JCMoptimizer extension for JCMsuite:

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:

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:

export JCMOPTIMIZER_CONFIG=/shared/software/config/jcmoptimizer.yml
$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:

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.

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:

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:

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

Metadata

Release files for jcmoptimizer 3.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jcmoptimizer 3.2.0
File Size Uploaded Provenance Actions
jcmoptimizer-3.2.0.tar.gz 66.3 kB Without provenance Details for jcmoptimizer-3.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jcmoptimizer 3.2.0
File Interpreter ABI Platform Actions
jcmoptimizer-3.2.0-py3-none-any.whl Python 3 none any Details for jcmoptimizer-3.2.0-py3-none-any.whl

Total release size: 126.3 kB

Release files / jcmoptimizer-3.2.0.tar.gz

Download URL jcmoptimizer-3.2.0.tar.gz
Size 66.3 kB
Tags Source
SHA-256 checksum
How to use checksums
e0bed4462556d588d89c7aaed551d8bab1fd97ecbdc8ac8df7e994bcf7d73d2f
BLAKE2b-256 checksum
How to use checksums
29053db1ec1cf25e56895acfe63b8b6ff625b8a2036df11d1347fdfba4ce62c5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.17

Release files / jcmoptimizer-3.2.0-py3-none-any.whl

Download URL jcmoptimizer-3.2.0-py3-none-any.whl
Size 59.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a9535ccd9daf12c7be80f7dce940d3c61568b31b9682b9b74e58da5e377376c6
BLAKE2b-256 checksum
How to use checksums
1791fd71bea0a42c33aec21d5d303df70c6c7f1b11c044a348f1d59c064a0650
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.17

Security for jcmoptimizer 3.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page