Metadata-Version: 2.4
Name: ascent-science
Version: 0.5.2
Summary: Licensed local optimizers and CIM hardware client for Ascent Science
Author: Ascent Science
License-Expression: LicenseRef-Proprietary
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: certifi>=2024.8.30

# Ascent Science Python SDK

Ascent Science SDK 0.5.2 separates two execution modes:

- `ascent.local.LocalOptimizer` executes exact and heuristic algorithms in the caller's Python process. It is intended for debugging, benchmarks, and small-scale workloads.
- `ascent.cim.CIMOptimizer` submits QUBO/Ising matrices to an explicitly configured real CIM gateway, polls task state, downloads the result, and caches successful results locally.

The hardware client never falls back to a simulator. Without `ASCENT_CIM_ENDPOINT`, construction raises `ConfigurationError`.

## Local execution

```python
from ascent.local import LocalOptimizer

optimizer = LocalOptimizer("qubo", method="exact")
result = optimizer.solve([[-2.0, 0.0], [0.0, -1.0]])
print(result.best_solution, result.best_value)
```

Supported pairs:

- `qubo/exact`
- `qubo/cim_simulator`
- `tsp/aco`
- `continuous/pso`

Concrete `ACOOptimizer`, `PSOOptimizer`, and `CIMSimulator` classes remain available from `ascent.local`.

## One-command ant colony solver

After the SDK is installed and activated, run the built-in TSP example directly:

```bash
ascent-aco
```

Use a JSON or CSV distance matrix for your own problem:

```bash
ascent-aco --matrix distances.json --ants 50 --iterations 300 --start-city 0
```

JSON input may be a two-dimensional array or an object with a `distance_matrix` field. Add
`--json` when the result will be consumed by another program.

## One-command particle swarm solver

Run the default two-dimensional Sphere benchmark:

```bash
ascent-pso
```

Choose an included objective and tune the search space:

```bash
ascent-pso --objective rastrigin --dimensions 5 --lower -5.12 --upper 5.12 \
  --particles 50 --iterations 300
```

Available command-line objectives are `sphere`, `rastrigin`, and `rosenbrock`. Python callers can
continue passing any callable objective to `LocalOptimizer("continuous", method="pso")`.

## CIM hardware execution

```python
from ascent.cim import CIMOptimizer

optimizer = CIMOptimizer(
    task_name="production-qubo",
    endpoint="https://your-real-cim-gateway.example/v1",
)
task = optimizer.solve_qubo([[-2.0, 0.0], [0.0, -1.0]])
result = task.wait(timeout=600)
print(result.best_solution, result.best_value, result.cached)
```

Set `ASCENT_CIM_ENDPOINT` instead of passing `endpoint` in application code. The configured service must implement `POST /tasks`, `GET /tasks/{id}`, `POST /tasks/{id}/cancel`, and `GET /tasks/{id}/logs`.

First-use SDK activation stores an owner-only license at `~/.ascent/license.json`. Hardware results are cached under `~/.ascent/cim-cache` unless caching is disabled.
