jcmoptimizer 3.0.9__tar.gz → 3.2.0__tar.gz

jcmoptimizer-3.2.0/PKG-INFO

@@ -0,0 +1,138 @@
+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.

jcmoptimizer-3.2.0/README.md

@@ -0,0 +1,118 @@
+# 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.

jcmoptimizer-3.2.0/jcmoptimizer/_progress.py

@@ -0,0 +1,44 @@
+"""Terminal progress driven by the client's existing event loop."""
+
+import asyncio
+import itertools
+import sys
+from typing import Any, Optional
+
+from ._runtime import drain
+from .requestor import inform
+
+
+class WorkingAnimation:
+    def __init__(self, message: str, enabled: bool = True) -> None:
+        self.message = message
+        self.enabled = enabled
+        self.stream = sys.stdout
+        self.animated = enabled and self.stream.isatty()
+        self._width = 0
+        self._task: Optional[asyncio.Task[None]] = None
+
+    def update(self, message: str) -> None:
+        self.message = message
+        if self.enabled and not self.animated:
+            inform(message)
+
+    async def _animate(self) -> None:
+        for frame in itertools.cycle("⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"):
+            text = f"{frame} {self.message}"
+            self._width = max(self._width, len(text))
+            self.stream.write("\r" + text.ljust(self._width))
+            self.stream.flush()
+            await asyncio.sleep(0.15)
+
+    async def __aenter__(self) -> "WorkingAnimation":
+        if self.animated:
+            self._task = asyncio.create_task(self._animate())
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        if self._task is not None:
+            self._task.cancel()
+            await drain(self._task)
+            self.stream.write("\r" + " " * self._width + "\r")
+            self.stream.flush()

jcmoptimizer-3.2.0/jcmoptimizer/_runtime.py

@@ -0,0 +1,273 @@
+"""One mode boundary for the native async interface and synchronous callers."""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import importlib
+import inspect
+import threading
+import traceback
+from collections.abc import Awaitable, Callable
+from concurrent.futures import TimeoutError as FutureTimeout
+from typing import Any, TypeVar
+
+Mode = TypeVar("Mode", bound=bool)
+T = TypeVar("T")
+
+
+_exit_callbacks: dict[Callable[[], None], None] = {}
+_exit_lock = threading.Lock()
+_exit_registered = False
+
+
+def register_exit_cleanup(callback: Callable[[], None]) -> None:
+    """Close blocking clients while asyncio's DNS executor is still usable."""
+    global _exit_registered
+    with _exit_lock:
+        if not _exit_registered:
+            # ThreadPoolExecutor uses threading's pre-join exit hooks. Import
+            # its hook first so ours runs before it, including with check=False.
+            importlib.import_module("concurrent.futures.thread")
+            # Available since Python 3.9, but omitted from threading's stubs.
+            threading._register_atexit(_close_at_exit)  # type: ignore[attr-defined]
+            _exit_registered = True
+        _exit_callbacks[callback] = None
+
+
+def unregister_exit_cleanup(callback: Callable[[], None]) -> None:
+    with _exit_lock:
+        _exit_callbacks.pop(callback, None)
+
+
+def _close_at_exit() -> None:
+    with _exit_lock:
+        callbacks = list(_exit_callbacks)
+    for callback in reversed(callbacks):
+        try:
+            callback()
+        except Exception:
+            # As with atexit, report unexpected failures and continue closing
+            # the remaining clients. Explicit close still propagates errors.
+            traceback.print_exc()
+
+
+async def settle(awaitable: Awaitable[T]) -> T:
+    """Settle a remote mutation before propagating cancellation to its owner."""
+    task = asyncio.ensure_future(awaitable)
+    try:
+        return await asyncio.shield(task)
+    except asyncio.CancelledError:
+        await drain(task)
+        raise
+
+
+async def drain(awaitable: Awaitable[T]) -> T | BaseException:
+    """Finish cleanup/recover a mutation even when cancellation is repeated."""
+    task = asyncio.ensure_future(awaitable)
+    while not task.done():
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError:
+            pass
+        except Exception:
+            break
+    try:
+        return task.result()
+    except BaseException as error:
+        return error
+
+
+class Runtime:
+    def __init__(self, asynchronous: bool = False) -> None:
+        self.asynchronous = asynchronous
+        self.closed = False
+        self.closing = False
+        self.sessions: list[Any] = []
+        self.active: set[asyncio.Task[Any]] = set()
+        self.loop: asyncio.AbstractEventLoop | None = None
+        self.thread: threading.Thread | None = None
+        self._start_lock = threading.Lock()
+
+    def bind(self) -> None:
+        loop = asyncio.get_running_loop()
+        if self.loop is None:
+            self.loop = loop
+        elif self.loop is not loop:
+            raise RuntimeError(
+                "Use an asynchronous client only on its owning event loop."
+            )
+
+    def _start(self) -> None:
+        with self._start_lock:
+            if self.thread is not None:
+                return
+            ready = threading.Event()
+
+            def serve() -> None:
+                self.loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(self.loop)
+                ready.set()
+                try:
+                    self.loop.run_forever()
+                finally:
+                    self.loop.run_until_complete(self.loop.shutdown_asyncgens())
+                    self.loop.run_until_complete(self.loop.shutdown_default_executor())
+                    self.loop.close()
+
+            self.thread = threading.Thread(
+                target=serve, name="jcmoptimizer-io", daemon=True
+            )
+            self.thread.start()
+            ready.wait()
+
+    def blocking(self, factory: Callable[[], Awaitable[T]]) -> T:
+        self._start()
+        if threading.current_thread() is self.thread:
+            raise RuntimeError(
+                "A blocking client call cannot run on its I/O loop; use Client(asynchronous=True)."
+            )
+        assert self.loop is not None
+        finished = threading.Event()
+
+        async def invoke() -> T:
+            try:
+                return await factory()
+            finally:
+                finished.set()
+
+        future = asyncio.run_coroutine_threadsafe(invoke(), self.loop)
+        try:
+            while True:
+                try:
+                    return future.result(timeout=0.1)
+                except FutureTimeout:
+                    if future.done():
+                        return future.result()
+        except KeyboardInterrupt:
+            future.cancel()
+            # The future becomes cancelled before coroutine cleanup has finished.
+            while not finished.wait(0.1):
+                pass
+            raise
+
+    async def execute(
+        self,
+        owner: Any,
+        function: Callable[..., Awaitable[T]],
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+    ) -> T:
+        self.bind()
+        name = function.__name__
+        if self.closed:
+            if name == "_async_close":
+                return None  # type: ignore[return-value]
+            raise RuntimeError("The JCMoptimizer client is closed.")
+        if name == "_async_close":
+            return await function(owner, *args, **kwargs)
+        if self.closing:
+            raise RuntimeError("The JCMoptimizer client is closing.")
+
+        async def invoke() -> T:
+            connect = getattr(owner, "_async_connect", None)
+            if connect is not None and name not in {"_async_connect", "_async_close"}:
+                await connect()
+            if name in {"_async_run", "_async_close", "_async_connect"} or getattr(
+                function, "__interruptible__", False
+            ):
+                return await function(owner, *args, **kwargs)
+            request = asyncio.ensure_future(function(owner, *args, **kwargs))
+            try:
+                return await asyncio.shield(request)
+            except asyncio.CancelledError:
+                result = await drain(request)
+                cleanup = getattr(owner, "_async_cancel_result", None)
+                if cleanup is not None and not isinstance(result, BaseException):
+                    await settle(cleanup(name, result))
+                raise
+
+        # Track the operation, not its caller: context exit may itself join close.
+        task = asyncio.create_task(invoke())
+        self.active.add(task)
+        try:
+            return await task
+        finally:
+            self.active.discard(task)
+
+    async def cancel_pending(self) -> None:
+        current = asyncio.current_task()
+        pending = [task for task in self.active if task is not current]
+        for task in pending:
+            if not getattr(task, "cancelling", lambda: 0)():
+                task.cancel()
+        await asyncio.gather(*pending, return_exceptions=True)
+
+    async def close_sessions(self) -> None:
+        for session in self.sessions:
+            await session.aclose()
+        self.sessions.clear()
+        self.closed = True
+
+    def stop(self) -> None:
+        if (
+            self.thread is not None
+            and self.loop is not None
+            and not self.loop.is_closed()
+        ):
+            self.loop.call_soon_threadsafe(self.loop.stop)
+            self.thread.join()
+
+
+def operation(
+    function: Callable[..., Awaitable[T]],
+    *,
+    name: str | None = None,
+    interruptible: bool = False,
+) -> Callable[..., Any]:
+    """Expose one coroutine through the client's explicit execution mode."""
+    public = name or function.__name__.removeprefix("_async_")
+    if interruptible:
+        setattr(function, "__interruptible__", True)
+
+    @functools.wraps(function)
+    def invoke(self: Any, *args: Any, **kwargs: Any) -> Any:
+        runtime: Runtime = self._runtime
+        if runtime.closed:
+            if function.__name__ == "_async_close":
+
+                async def closed() -> None:
+                    return None
+
+                return closed() if runtime.asynchronous else None
+            raise RuntimeError("The JCMoptimizer client is closed.")
+        factory = lambda: runtime.execute(self, function, args, kwargs)
+        if runtime.asynchronous:
+            return factory()
+        try:
+            return runtime.blocking(factory)
+        except KeyboardInterrupt:
+            if public != "run":
+                raise
+            from .requestor import warn
+
+            warn("Study stopped.")
+            return None
+        finally:
+            if runtime.closed:
+                runtime.stop()
+
+    invoke.__name__ = public
+    invoke.__qualname__ = function.__qualname__.rsplit(".", 1)[0] + "." + public
+    invoke.__doc__ = inspect.cleandoc(function.__doc__ or "")
+    if not function.__qualname__.startswith("Server."):
+        invoke.__doc__ += "\n\nWith ``Client(asynchronous=True)``, await this method."
+    return invoke
+
+
+def blocking_property(owner: Any, getter: str) -> Any:
+    if owner._runtime.asynchronous:
+        raise RuntimeError(
+            f"This property performs I/O. Use await {getter}() with an asynchronous client."
+        )
+    return getattr(owner, getter)()