Metadata-Version: 2.4
Name: ascent-science
Version: 0.7.0
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
Provides-Extra: or
Requires-Dist: highspy<2,>=1.12; extra == "or"
Requires-Dist: ortools>=9.11; extra == "or"
Provides-Extra: data
Requires-Dist: openpyxl>=3.1; extra == "data"
Requires-Dist: pandas>=2.2; extra == "data"
Provides-Extra: ml
Requires-Dist: scikit-learn>=1.5; extra == "ml"
Provides-Extra: all
Requires-Dist: highspy<2,>=1.12; extra == "all"
Requires-Dist: openpyxl>=3.1; extra == "all"
Requires-Dist: ortools>=9.11; extra == "all"
Requires-Dist: pandas>=2.2; extra == "all"
Requires-Dist: scikit-learn>=1.5; extra == "all"

# Ascent Science Python SDK

Ascent Science SDK 0.7.0 is installed as one complete distribution. Algorithms
are organized by type and selected through Python subpackages:

```bash
python -m pip install --upgrade ascent-science==0.7.0
```

```python
import ascent

aco = ascent.combinatorial.ACOOptimizer(ants=30, iterations=100)
pso = ascent.combinatorial.PSOOptimizer(particles=30, iterations=100)
exact = ascent.qubo.ExactQUBOOptimizer()
simulator = ascent.qubo.CIMSimulator()
hardware = ascent.cim.CIMOptimizer(task_name="production-qubo")
```

Algorithm namespaces follow the platform algorithm repository exactly:

| Repository category | SDK namespace | Currently packaged algorithms |
| --- | --- | --- |
| 量子算法 | `ascent.quantum` | — |
| 组合优化 | `ascent.combinatorial` | `ACOOptimizer`, `PSOOptimizer` |
| 精确求解 | `ascent.exact` | — |
| 图算法 | `ascent.graph` | — |
| 前沿图优化 | `ascent.frontier_graph` | — |
| 连续优化 | `ascent.continuous` | — |
| 机器学习 | `ascent.machine_learning` | — |
| 时间序列 | `ascent.time_series` | — |
| 信号与图像 | `ascent.signal_image` | — |
| 多目标优化 | `ascent.multiobjective` | — |
| 运筹 OR | `ascent.operations_research` | — |
| 经典科学计算 | `ascent.scientific_computing` | — |

Only implemented and packaged algorithms are exposed as callable classes.
Prototype and planned entries shown in the web directory are not represented as
working SDK classes. `ascent.qubo`, `ascent.cim`, and `ascent.core` are
cross-category functional modules rather than repository
algorithm categories.

The SDK also separates problem models, solver capabilities, and two execution modes:

- `ascent.core` provides stable `Problem`, `Solver`, `SolveResult`, registry, and QUBO/Ising transformation contracts.
- `QuboProblem`, `IsingProblem`, `TSPProblem`, and `ContinuousProblem` decouple a problem from the selected solver.

- Category optimizer classes execute local algorithms in the caller's Python process.
- `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
import ascent

optimizer = ascent.qubo.ExactQUBOOptimizer()
result = optimizer.solve_qubo([[-2.0, 0.0], [0.0, -1.0]])
print(result.best_solution, result.best_value)
```

Named QUBO models and hardware-oriented precision reduction are available without another package:

```python
from ascent import QuboBuilder, reduce_precision

builder = QuboBuilder()
builder.binary("x")
builder.binary("y")
problem = builder.add_linear_equality({"x": 1, "y": 1}, 1, penalty=5).build()
prepared = reduce_precision(problem.matrix, maximum_absolute=1.0, decimal_places=6)
```

The wheel is pure Python and universal across supported operating systems. Install the single
`ascent_science-0.7.0-py3-none-any.whl` artifact; platform-specific wheel tags are not used.

After first activation, local solvers validate the cached license offline by default. Set
`ASCENT_LICENSE_VALIDATION=online` when each solver construction must check revocation online.

## 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 pass
any callable objective to `ascent.combinatorial.PSOOptimizer`.

## 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.
