Metadata-Version: 2.4
Name: ascent-science
Version: 0.8.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.8.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.8.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.8.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.

## Ant colony optimizer

Create the concrete optimizer from its algorithm category, then pass a distance matrix to
`solve_tsp`:

```python
import ascent

distance_matrix = [
    [0, 2, 9, 10],
    [2, 0, 6, 4],
    [9, 6, 0, 8],
    [10, 4, 8, 0],
]

solver = ascent.combinatorial.ACOOptimizer(ants=30, iterations=100, seed=42)
result = solver.solve_tsp(distance_matrix, start_city=0)
print(result.best_route, result.best_distance)
```

## Particle swarm optimizer

Pass any callable objective and one `(lower, upper)` pair for each dimension:

```python
import ascent

def sphere(position):
    return sum(value * value for value in position)

solver = ascent.combinatorial.PSOOptimizer(particles=30, iterations=100, seed=42)
result = solver.solve(sphere, bounds=[(-5.0, 5.0), (-5.0, 5.0)])
print(result.best_position, result.best_value)
```

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