# Morphantic Optimizer Client SDK
This package provides a Python client for interacting with the Morphantic (Advanced Archipelago Evolution) Optimizer as a Service. It allows you to leverage the power of the Morphantic algorithm to solve complex, multi-objective optimization problems without exposing your proprietary evaluation logic.
## How It Works
The Morphantic Optimizer runs on a remote server, while your proprietary evaluation function (the `metrics_fn`) runs securely on your own machine. The client SDK facilitates this interaction through a secure callback mechanism:
1. You define your optimization problem using `ObjectiveSpec` objects.
2. You provide your `metrics_fn`, which takes a solution vector and returns a dictionary of performance metrics.
3. When you call `client.optimize()`, the SDK starts a temporary, local web server (a "worker") that wraps your `metrics_fn`.
4. The SDK sends the problem definition and the URL of your local worker to the Morphantic server.
5. The Morphantic server runs the optimization, calling back to your worker to evaluate each candidate solution.
6. Once complete, the SDK retrieves the final result and shuts down the local worker.
This ensures your intellectual property (the `metrics_fn`) never leaves your infrastructure.
## Installation
```bash
pip install morphantic-core
```
## Quickstart Example
Here is a simple example of optimizing a 2D function.
```python
import numpy as np
from Morphantic_client import MorphanticClient, ObjectiveSpec
# 1. Define your proprietary metrics function
def my_metrics_fn(x: np.ndarray) -> dict:
# Objective 1: Minimize a sphere function
cost = np.sum(x**2)
# Objective 2: Maximize a linear function
performance = np.sum(x)
return {"cost": cost, "performance": performance}
# 2. Define your objectives for the API
objectives = [
ObjectiveSpec(name="cost", weight=0.7, baseline=50.0, target=0.1, direction="min"),
ObjectiveSpec(name="performance", weight=0.3, baseline=0.0, target=10.0, direction="max")
]
# 3. Initialize the client and run the optimization
# Replace with your production server URL
Morphantic_SERVER_URL = "https://testserver.morphantic.com"
client = MorphanticClient(server_url=Morphantic_SERVER_URL)
# Note: For cloud/Docker environments, you must provide your public IP
# via the `worker_host` argument.
final_result = client.optimize(
objectives=objectives,
metrics_fn=my_metrics_fn,
dimension=2,
bounds=(-5.0, 5.0),
max_generations=50,
pop_size=100
)
print(final_result)
```
### API Reference
#### `MorphanticClient(server_url: str)`
The main client class.
#### `client.optimize(...)`
Starts and manages an optimization job.
**Arguments:**
- `objectives` (List[ObjectiveSpec]): A list of `ObjectiveSpec` objects defining the problem.
- `metrics_fn` (Callable): Your evaluation function. Must accept a NumPy array and return a dictionary of metrics.
- `dimension` (int): The number of parameters in your solution vector.
- `bounds` (Tuple[float, float]): The `(min, max)` bounds for each parameter.
- `worker_port` (int, optional): The local port for the callback worker. Defaults to `8081`.
- `worker_host` (str, optional): The public IP or hostname of the machine running the client. **Required for non-local servers (e.g., cloud, Docker).** If `None`, a local IP is auto-detected.
- `pop_size`, `max_generations`, `n_islands`, `seed`: Standard parameters to configure the Morphantic optimizer.
- `poll_interval` (int, optional): Seconds to wait between polling for results. Defaults to `10`.
**Returns:**
A dictionary containing the final job status, best solution, and final metrics.
Raw data
{
"_id": null,
"home_page": null,
"name": "morphantic-core",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "optimization, evolutionary, optuna, surrogate, trust-region",
"author": null,
"author_email": "Morphantic <help@morphantic.com>",
"download_url": "https://files.pythonhosted.org/packages/f1/50/801a544a4fdce34cc3eeb8404475976aefe86716c051fc0baf2ab8e13e8d/morphantic_core-0.1.1.tar.gz",
"platform": null,
"description": "# Morphantic Optimizer Client SDK\n\nThis package provides a Python client for interacting with the Morphantic (Advanced Archipelago Evolution) Optimizer as a Service. It allows you to leverage the power of the Morphantic algorithm to solve complex, multi-objective optimization problems without exposing your proprietary evaluation logic.\n\n## How It Works\n\nThe Morphantic Optimizer runs on a remote server, while your proprietary evaluation function (the `metrics_fn`) runs securely on your own machine. The client SDK facilitates this interaction through a secure callback mechanism:\n\n1. You define your optimization problem using `ObjectiveSpec` objects.\n2. You provide your `metrics_fn`, which takes a solution vector and returns a dictionary of performance metrics.\n3. When you call `client.optimize()`, the SDK starts a temporary, local web server (a \"worker\") that wraps your `metrics_fn`.\n4. The SDK sends the problem definition and the URL of your local worker to the Morphantic server.\n5. The Morphantic server runs the optimization, calling back to your worker to evaluate each candidate solution.\n6. Once complete, the SDK retrieves the final result and shuts down the local worker.\n\nThis ensures your intellectual property (the `metrics_fn`) never leaves your infrastructure.\n\n## Installation\n\n```bash\npip install morphantic-core\n```\n\n## Quickstart Example\n\nHere is a simple example of optimizing a 2D function.\n\n```python\nimport numpy as np\nfrom Morphantic_client import MorphanticClient, ObjectiveSpec\n\n# 1. Define your proprietary metrics function\ndef my_metrics_fn(x: np.ndarray) -> dict:\n # Objective 1: Minimize a sphere function\n cost = np.sum(x**2)\n # Objective 2: Maximize a linear function\n performance = np.sum(x)\n return {\"cost\": cost, \"performance\": performance}\n\n# 2. Define your objectives for the API\nobjectives = [\n ObjectiveSpec(name=\"cost\", weight=0.7, baseline=50.0, target=0.1, direction=\"min\"),\n ObjectiveSpec(name=\"performance\", weight=0.3, baseline=0.0, target=10.0, direction=\"max\")\n]\n\n# 3. Initialize the client and run the optimization\n# Replace with your production server URL\nMorphantic_SERVER_URL = \"https://testserver.morphantic.com\"\nclient = MorphanticClient(server_url=Morphantic_SERVER_URL)\n\n# Note: For cloud/Docker environments, you must provide your public IP\n# via the `worker_host` argument.\nfinal_result = client.optimize(\n objectives=objectives,\n metrics_fn=my_metrics_fn,\n dimension=2,\n bounds=(-5.0, 5.0),\n max_generations=50,\n pop_size=100\n)\n\nprint(final_result)\n```\n\n### API Reference\n\n#### `MorphanticClient(server_url: str)`\n\nThe main client class.\n\n#### `client.optimize(...)`\n\nStarts and manages an optimization job.\n\n**Arguments:**\n\n- `objectives` (List[ObjectiveSpec]): A list of `ObjectiveSpec` objects defining the problem.\n- `metrics_fn` (Callable): Your evaluation function. Must accept a NumPy array and return a dictionary of metrics.\n- `dimension` (int): The number of parameters in your solution vector.\n- `bounds` (Tuple[float, float]): The `(min, max)` bounds for each parameter.\n- `worker_port` (int, optional): The local port for the callback worker. Defaults to `8081`.\n- `worker_host` (str, optional): The public IP or hostname of the machine running the client. **Required for non-local servers (e.g., cloud, Docker).** If `None`, a local IP is auto-detected.\n- `pop_size`, `max_generations`, `n_islands`, `seed`: Standard parameters to configure the Morphantic optimizer.\n- `poll_interval` (int, optional): Seconds to wait between polling for results. Defaults to `10`.\n\n**Returns:**\n\nA dictionary containing the final job status, best solution, and final metrics.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Morphantic Core: modular evolutionary optimization with safe exploration, drift guard, and Optuna integration.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/morphantic/morphantic-core",
"Issues": "https://github.com/morphantic/morphantic-core/issues"
},
"split_keywords": [
"optimization",
" evolutionary",
" optuna",
" surrogate",
" trust-region"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "babab473f15d57c8fc956b5d90a417a989d3cb2135e23ca1c6c55244f3d7d9da",
"md5": "8b3f8bbc18a5ae9c976c74678812a98d",
"sha256": "15f83dab9472d5b6ab83da9df110813297bfaf8e827631247c38a69a3ce0c732"
},
"downloads": -1,
"filename": "morphantic_core-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8b3f8bbc18a5ae9c976c74678812a98d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 6475,
"upload_time": "2025-08-23T03:14:38",
"upload_time_iso_8601": "2025-08-23T03:14:38.092478Z",
"url": "https://files.pythonhosted.org/packages/ba/ba/b473f15d57c8fc956b5d90a417a989d3cb2135e23ca1c6c55244f3d7d9da/morphantic_core-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f150801a544a4fdce34cc3eeb8404475976aefe86716c051fc0baf2ab8e13e8d",
"md5": "388af36d5669364e4e4c208e83ed07a3",
"sha256": "4f01fbc4291a4ed7d45115423042c62ab3aa62637c231c2e3eb2875686f76049"
},
"downloads": -1,
"filename": "morphantic_core-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "388af36d5669364e4e4c208e83ed07a3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 6972,
"upload_time": "2025-08-23T03:14:38",
"upload_time_iso_8601": "2025-08-23T03:14:38.999420Z",
"url": "https://files.pythonhosted.org/packages/f1/50/801a544a4fdce34cc3eeb8404475976aefe86716c051fc0baf2ab8e13e8d/morphantic_core-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-23 03:14:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "morphantic",
"github_project": "morphantic-core",
"github_not_found": true,
"lcname": "morphantic-core"
}
JSON
