User Guide

Installation

The package is published on PyPI and can be installed with Poetry or pip:

pip install min-ratio-cycle

For development, clone the repository and install in editable mode:

git clone https://github.com/DiogoRibeiro7/min_ratio_cycle.git
cd min_ratio_cycle
poetry install

Basic Usage

Construct a solver from edge lists and retrieve the optimal cycle:

from min_ratio_cycle.solver import MinRatioCycleSolver
solver = MinRatioCycleSolver([(0, 1, 3, 1), (1, 2, 2, 1), (2, 0, 4, 1)])
result = solver.solve()
cycle, cost, time, ratio = result

Advanced Usage

The solver exposes both numeric and exact modes. Use mode="exact" for integer weights to avoid floating point error or tolerance to trade accuracy for speed in numeric mode:

solver.solve(mode="exact")
solver.solve(tolerance=1e-6)

Error Handling

All solver issues derive from min_ratio_cycle.exceptions.SolverError. Typical failures include:

• GraphStructureError – raised for disconnected graphs or invalid indices. Recheck the edge list.

• NumericalInstabilityError – occurs when weights span too many orders of magnitude. Try scaling your inputs.

• ResourceExhaustionError – emitted when memory or time limits are exceeded. Increase limits or simplify the graph.

Each exception provides fix_suggestion and recovery_hint fields to help resolve the problem.

Performance Tuning

Choose the numeric solver for dense graphs and the exact solver for small integer-weight graphs. Tighten tolerance for more precision, or loosen it for faster solves. The limit parameter caps relaxations to prevent runaway iterations.

Real-World Examples

The utility module ships with DIMACS helpers:

from min_ratio_cycle.benchmarks import load_dimacs, benchmark_solver
graph = load_dimacs("tests/data/triangle.dimacs")
stats = benchmark_solver(graph)
print(stats.runtime, stats.ratio)

Troubleshooting

Symptom	Diagnosis	Solution
NaN ratio	Graph contains negative times	Ensure all transit times > 0
Timeout	Graph too large	Increase timeout or simplify
No cycle found	Graph is acyclic	Check input or allow exact mode