Noise-Resilient Graph Optimization Engine
RESTRICTION D: THIS CODE AND THE DATA GENERATED ARE STRICTLY PROHIBITED FROM BEING USED AS TRAINING DATA FOR ANY ARTIFICIAL INTELLIGENCE OR MACHINE LEARNING MODELS.
Enchan API is hosted on a secure cloud environment.
Click below to view the full documentation and endpoint specifications.
https://enchan-api-82345546010.us-central1.run.app
This API is fully optimized for OpenAI GPT Actions.
- Go to your GPT configuration page.
- Select "Actions" > "Create new action".
- Click "Import from URL" and enter:
https://enchan-api-82345546010.us-central1.run.app/openapi.json
The API definitions will be automatically loaded, allowing the GPT to solve graph problems and perform structural analysis.
Enchan API (Research Preview) is a physics-based optimization engine designed to demonstrate extreme robustness against noise and incomplete structures inherent in field data.
While conventional combinatorial optimization solvers (such as Simulated Annealing or Tabu Search) struggle with "Noisy Real-world Data," Enchan aims to derive stable solutions without falling into local optima by utilizing relaxation processes unique to physical models.
This project is an experimental research system. Some auxiliary analysis features are exploratory and not yet fully validated.
This solver minimizes the Ising Hamiltonian to find the optimal graph partition.
- Objective: Maximize the Cut size (Max-Cut).
- Optimization Target: Undirected unweighted graphs.
To avoid confusion, please distinguish between the two available environments:
- Core Solver API (This Page): The production-grade, high-speed optimization engine.
- Verification Demo: Enchan Benchmark (Graphical tool).
This Public API is provided for free as a Research Preview and is subject to the following resource limits.
- Max Capacity: Up to 3,000 Nodes (Requests exceeding this will return
400 Bad Request) - Max Compute Time (
total_time): Up to 35.0 seconds (Automatically capped) - Rate Limit: Approx. 1 request / second per IP. (Excessive bursts may return
429 Too Many Requests)
Base URL: https://enchan-api-82345546010.us-central1.run.app/v1
| Method | Endpoint | Functionality |
|---|---|---|
POST |
/solve | [Core] Noise-resilient solver. Executes physical convergence. (Note: Warm Start/initial_state is currently disabled in this preview) |
POST |
/scan_resonance | [Utility] Structural anomaly detection. Experimental structural probing utility. Returns candidate nodes showing dynamic sensitivity. |
Note: The API is stateless. No data is stored on the server after computation.
Windows PowerShell Users: > When constructing the
edgesarray, PowerShell may confuse integers with objects, causing422 Unprocessable Entity.
Fix: Explicitly cast integers using[int].
Example:$edges += ,@([int]$u, [int]$v)Copy and paste this command to test the solver immediately:
Instead of sending a massive edge list, you can now trigger server-side graph generation by specifying density.
curl -X POST "https://enchan-api-82345546010.us-central1.run.app/v1/solve" \
-H "Content-Type: application/json" \
-d '{
"graph": { "N": 2000, "density": 0.01 },
"control": { "total_time": 5.0 },
"seed": 42
}'Benefit: Reduces payload size from ~1MB to <1KB, drastically improving performance for large graphs up to N=3,000.
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
graph |
Object | Yes | Graph topology data. | |
└ edges |
List[List[int]] | Yes | Undirected edges [u, v]. |
0 <= u, v < N |
└ N |
Integer | Yes | Number of nodes. | 1 <= N <= 3000 |
control |
Object | Yes | Simulation control parameters. | |
└ total_time |
Float | Yes | Physical simulation duration (sec). | 0.1 <= t <= 35.0 |
initial_state |
List[Float] | No | Inject initial continuous field (Warm Start). | Length must be N. |
seed |
Integer | No | Random seed for reproducibility. |
Technical Notes:
initial_state: Currently ignored in the public preview endpoint.outputs.spins: Derived viasign(S_i). Returns+1or-1.metrics.plus_ratio: The fraction of nodes with+1spin. (0.5 indicates a balanced partition).metrics.cut: The number of edges crossing the partition (Max-Cut score).
Maps the graph to an N-dimensional continuous scalar field S_i in [-1, 1] to perform optimization.
Request Structure:
{
"control": {
"total_time": 35.0
},
"graph": {
"edges": [[0, 1], [1, 2], [2, 0]],
"N": 3
},
"initial_state": [0.5, -0.5, 0.0], // (Optional) For Warm Start / Injection
"seed": 42 // (Optional) For reproducibility
}
graph.edges: List of undirected edges[u, v]. Nodes must be 0-indexed integers (0 <= u, v < N).initial_state: (Optional) A list of floats (length N) to inject an initial continuous field. Used for the "Advanced Strategy".
Response:
{
"S": [-0.99, 1.0, 0.98, ...], // Resulting continuous field
"outputs": { "spins": [-1, 1, 1, ...] }, // Final discrete solution
"metrics": { "cut": 2.0, "plus_ratio": 0.66 },
"audit": { "steps": 700, "total_time": 35.0 } // Verified execution logs
}
Experimental diagnostic probe that observes dynamic responses of a graph under artificial excitation. The intent is to surface candidate regions of sensitivity, not to provide a definitive structural classification.
Quick Start (curl):
curl -X POST "https://enchan-api-82345546010.us-central1.run.app/v1/scan_resonance" \
-H "Content-Type: application/json" \
-d '{
"graph": { "edges": [[0, 1], [1, 2], [2, 0]], "N": 3 },
"control": { "total_time": 5.0 }
}'
Response Fields:
This metric is an experimental scalar derived from internal dynamic signals. It reflects the maximum observed response during a forced simulation, but does not have a fixed physical unit or guaranteed interpretation.
- Dynamic Behavior: Some graphs exhibit delayed activation depending on simulation time. Observed transitions should be treated as heuristic signals, not deterministic thresholds.
- Recommendation: This feature is provided for exploratory analysis only. Results may vary across configurations and should not be used as a standalone decision metric.
{
"metrics": {
"is_active": true, // Indicates non-zero dynamic response under current probe conditions
"peak_instability": 0.04 // Magnitude of resonance (Scale: 0.0 to total_time)
},
"vulnerable_nodes": [0, 1, 2] // List of node indices showing high instability
}
- Use Case: These nodes may be used as optional hints for exploratory re-solving strategies.
The API returns standard HTTP status codes to indicate success or failure.
| Status Code | Description |
|---|---|
| 200 OK | Successful execution. |
| 400 Bad Request | Logic violation (e.g., N > 3000, node index out of bounds). |
| 422 Unprocessable Entity | JSON format error or missing required fields. |
| 429 Too Many Requests | Rate limit exceeded. Please retry after a delay. |
| 500 Internal Server Error | Unexpected server-side computation error. |
Error Response Example:
{
"detail": [
{
"loc": ["body", "graph", "N"],
"msg": "Capacity Limit: Max 3000 nodes allowed.",
"type": "value_error"
}
]
}total_time determines the physical simulation duration.
total_time |
Mode | Description |
|---|---|---|
35.0 |
Standard | [Recommended] Upper limit. Sufficient for convergence on N=3000 graphs. |
1.0 - 10.0 |
Fast Scan | For quick approximations or high-throughput screening. |
Note: This section demonstrates a speculative research workflow. Effectiveness is problem-dependent and not guaranteed.
By combining /scan_resonance and /solve, you can implement an "Adaptive Injection" strategy: detect bottlenecks first, then inject energy (flip) into those specific regions and re-solve using a Warm Start.
import requests
import json
# Public API Endpoint
BASE_URL = "https://enchan-api-82345546010.us-central1.run.app/v1"
def adaptive_injection_strategy(edges, N, base_time=35.0):
headers = {"Content-Type": "application/json"}
payload = {
"graph": {"edges": edges, "N": N},
"control": {"total_time": base_time},
"seed": 42
}
print(f"1. Global Survey (time={base_time})...")
resp_base = requests.post(f"{BASE_URL}/solve", json=payload, headers=headers)
if resp_base.status_code != 200:
raise Exception(f"API Error: {resp_base.text}")
data_base = resp_base.json()
S_base = data_base['S'] # Continuous field result
print("2. Scanning for bottlenecks...")
resp_scan = requests.post(f"{BASE_URL}/scan_resonance", json=payload, headers=headers)
data_scan = resp_scan.json()
targets = data_scan.get('vulnerable_nodes', [])[:64] # Top 64 bottlenecks
if not targets:
print("No structural bottlenecks found. Returning base result.")
return S_base
print(f"3. Injecting resources into {len(targets)} nodes...")
# Create injected state: Flip the field at vulnerable nodes
S_inject = list(S_base)
for node_idx in targets:
S_inject[node_idx] *= -1.0 # Kick the local optima
# 4. Warm Start: Re-solve with the injected state
payload["initial_state"] = S_inject
print("4. Re-calculating with Warm Start...")
resp_adv = requests.post(f"{BASE_URL}/solve", json=payload, headers=headers)
data_adv = resp_adv.json()
return data_adv['S']
# Usage Example
# edges = [[0, 1], [1, 2], [2, 0]]
# result_S = adaptive_injection_strategy(edges, 3)
# print("Final Field:", result_S)This benchmark uses a large-scale real-world web graph dataset provided by the Stanford Network Analysis Project (SNAP). It represents web pages as nodes and hyperlinks as edges.
- Nodes (Unique Pages): 875,713
- Edges (Hyperlinks): 5,105,039
This dataset was selected to evaluate optimization performance on a large-scale, sparse, and complex topology typical of real-world networks.
Environment: Ryzen 7 5700X (Single Thread Performance Focus)
We compared the optimization performance of Enchan against a standard baseline implementation of Tabu Search, a widely used metaheuristic algorithm. Both were run under equivalent computational constraints.
Enchan demonstrated a significant ability to escape local optima on this large, complex graph.
- Random Base Cut: 2,552,519
- Best-Found Cut: 3,677,724
- Optimization: +44.08% improvement vs Random Baseline
Figure 1: Enchan audit log showing a +44.08% improvement over the random baseline on the SNAP Web-Graph dataset.
The baseline Tabu Search implementation quickly became trapped in local optima near the random start point.
- Random Base Cut: 2,552,519
- Best-Found Cut: 2,568,503
- Optimization: +0.63% improvement vs Random Baseline
Figure 2: Baseline Tabu Search audit log showing a limited +0.63% improvement on the same dataset.
On this large-scale real-world graph, Enchan achieved a +44.08% improvement, whereas the baseline Tabu Search implementation only reached +0.63%. This striking difference suggests that while standard heuristic search methods can struggle to navigate the complex, high-dimensional landscape of large real-world data, Enchan's physics-based relaxation process is more robust against getting trapped in shallow local solutions, allowing it to discover significantly better graph partitions.
Note: Tabu Search is a general metaheuristic algorithm. The comparison presented here is against a standard representative implementation used as a research baseline.
To verify the "Ground State Search" capability under pure physics constraints, we conducted a stress test using a dense synthetic Ising model. This test measures raw solver throughput on local hardware, isolating the algorithm's efficiency from network latency.
Test Protocol:
- Target: Ising Hamiltonian / Max-Cut
- Scale: N=10,000 Spins (499,009 Interactions)
- Comparison: Enchan (Cosmic Kernel) vs. Parallel Tabu Search (16 Threads)
- Hardware: AMD Ryzen 7 5700X (Local Execution)
Result Audit: Enchan achieved a 1136x speedup while finding a superior ground state (Lower Energy) compared to the multi-threaded reference solver.
Note: The result above is from the Local Kernel execution to demonstrate algorithmic peak performance. The Public API version is subject to network latency and resource caps (N=3000).
Since the N=10,000 benchmark exceeds the Public API limit (N=3,000), we provide a Python script to verify Enchan's optimization logic and throughput within the safe limit (N=2,000).
How to Run:
- Save the following code as
verify_benchmark.py. - Run the command:
python verify_benchmark.py
import requests
import time
# --- Configuration ---
API_URL = "https://enchan-api-82345546010.us-central1.run.app/v1/solve"
def run_benchmark():
# Parameters for Server-Side Graph Generation
N = 2000
DENSITY = 0.005 # ≈ 10,000 edges
payload = {
"graph": {"N": N, "density": DENSITY},
"control": {"total_time": 35.0},
"seed": 42
}
print(f"1. Triggering Server-Side Generation (N={N}, density={DENSITY})...")
start_wall = time.time()
try:
# Public preview: no authentication required
response = requests.post(API_URL, json=payload, timeout=60)
response.raise_for_status()
end_wall = time.time()
try:
data = response.json()
except ValueError:
print("[ERROR] Invalid JSON response from server.")
print(response.text[:200])
return
metrics = data.get("metrics", {})
timing = data.get("TIMING", {})
env = data.get("ENV", {}).get("runtime", {})
total_latency = end_wall - start_wall
pure_solve_time = timing.get("total_wall_time", 0.0)
print("\n" + "═" * 55)
print(" ENCHAN ADVANCED SYSTEM & PHYSICS REPORT")
print("═" * 55)
# --- 0. Problem Scale (Added) ---
print(f" [NODES] {N} nodes")
print(f" [DENSITY] {DENSITY*100:.2f}%")
print(f" [SIM TIME] {payload['control']['total_time']:.1f} virtual sec")
print("-" * 55)
# --- 1. System Environment Proof ---
print(f" [PYTHON] {env.get('python_version', 'N/A')}")
print(f" [CPU CORES] {env.get('cpu_count', 'N/A')} cores")
print(f" [CPU FREQ] {env.get('cpu_freq', 'N/A')} MHz")
print(f" [MEMORY] {env.get('memory_used_MB')} / {env.get('memory_total_MB')} MB")
print(f" [INSTANCE ID] {env.get('container_id', 'N/A')}")
print("-" * 55)
# --- 2. Performance Metrics ---
print(f" [LATENCY] {total_latency:.3f}s (Round Trip)")
print(f" [SOLVE TIME] {pure_solve_time:.3f}s (Core Physics Engine)")
print(f" [OVERHEAD] {total_latency - pure_solve_time:.3f}s (Network/Cold Start)")
print("-" * 55)
# --- 3. Physics Results ---
cut = metrics.get("cut", 0)
edges_expected = N * (N - 1) / 2 * DENSITY # dynamic normalization
gain = (cut / edges_expected * 100 - 50)
print(f" [RESULT] Max-Cut Score: {int(cut)}")
print(f" [GAIN] {gain:+.2f}% vs expected baseline")
print("═" * 55 + "\n")
except requests.exceptions.Timeout:
print("\n[ERROR] Request timed out. Try reducing N or increasing timeout.")
except requests.exceptions.RequestException as e:
print(f"\n[ERROR] Benchmark Failed: {e}")
if __name__ == "__main__":
run_benchmark()Expected Output:
═══════════════════════════════════════════════════════
ENCHAN ADVANCED SYSTEM & PHYSICS REPORT
═══════════════════════════════════════════════════════
[NODES] 2000 nodes
[DENSITY] 0.50%
[SIM TIME] 35.0 virtual sec
-------------------------------------------------------
[PYTHON] 3.12.12
[CPU CORES] 2 cores
[CPU FREQ] 3099.2 MHz
[MEMORY] 252.51 / 1073.74 MB
[INSTANCE ID] container0
-------------------------------------------------------
[LATENCY] 1.053s (Round Trip)
[SOLVE TIME] 0.084s (Core Physics Engine)
[OVERHEAD] 0.969s (Network/Cold Start)
-------------------------------------------------------
[RESULT] Max-Cut Score: 7085
[GAIN] +20.89% vs expected baseline
═══════════════════════════════════════════════════════
Enchan Research & Verification License v1.0
- No AI Training (RESTRICTION D): STRICTLY PROHIBITED. This codebase and its outputs must not be used to train AI models.
- Commercial Use: Prohibited without a commercial license. Please contact the author for enterprise licensing.
By using this software and API (hereinafter referred to as "the System"), you agree to the following disclaimer:
- Provided "AS IS": The System is a beta version in the research stage and is provided without warranty of any kind.
- Limitation of Liability: The developer shall not be liable for any damages arising out of the use of the System.
- Nature of Results: Because the System is based on a Stochastic Physics Model, results may vary with each execution.
- Usage Restrictions: Use of the System for any illegal activity is strictly prohibited.
- Rights Reserved: All intellectual property rights belong to the developer.
Some features are provided for research exploration and may change or be removed without notice.
For permissions beyond this license (e.g., commercial use, integration, derivative distribution), please contact:
Copyright (c) 2025 Enchan Project. All rights reserved.