Skip to content

OptimizationApi.md

Latest commit

 

History

History
642 lines (422 loc) · 21.5 KB

OptimizationApi.md

File metadata and controls

642 lines (422 loc) · 21.5 KB
Raw

touroptimizer_py_client.OptimizationApi

All URIs are relative to http://localhost

Method HTTP request Description
get_run_result GET /api/v1/runs/{runId}/result Retrieve the full result of a run (blocks until complete).
get_run_solution GET /api/v1/runs/{runId}/solution Retrieve the solution of a run (blocks until complete).
get_started_signal GET /api/v1/runs/{runId}/started Emits once the run has transitioned to the running state.
start_run POST /api/v1/runs Start an optimization run and return a runId.
stop_run DELETE /api/v1/runs/{runId} Stop an active optimization run gracefully.
stream_errors GET /api/v1/runs/{runId}/stream/errors SSE stream of optimization errors for a run.
stream_progress GET /api/v1/runs/{runId}/stream/progress SSE stream of optimization progress for a run.
stream_status GET /api/v1/runs/{runId}/stream/status SSE stream of optimization status messages for a run.
stream_warnings GET /api/v1/runs/{runId}/stream/warnings SSE stream of optimization warnings for a run.

get_run_result

RestOptimization get_run_result(run_id)

Retrieve the full result of a run (blocks until complete).

Blocks the connection until the optimization finishes or the timeout is reached. Returns 504 if the optimizer has not finished within the connection timeout. If you expect runs longer than a few minutes, use POST /api/v1/jobs instead.

Example

import touroptimizer_py_client
from touroptimizer_py_client.models.rest_optimization import RestOptimization
from touroptimizer_py_client.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to http://localhost
# See configuration.py for a list of all supported configuration parameters.
configuration = touroptimizer_py_client.Configuration(
    host = "http://localhost"
)


# Enter a context with an instance of the API client
with touroptimizer_py_client.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = touroptimizer_py_client.OptimizationApi(api_client)
    run_id = 'run_id_example' # str | Run identifier returned by POST /api/v1/runs.

    try:
        # Retrieve the full result of a run (blocks until complete).
        api_response = api_instance.get_run_result(run_id)
        print("The response of OptimizationApi->get_run_result:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling OptimizationApi->get_run_result: %s\n" % e)

Parameters

Name Type Description Notes
run_id str Run identifier returned by POST /api/v1/runs.

Return type

RestOptimization

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status code Description Response headers
200 Optimization finished. Full RestOptimization result returned. -
404 No active run found for this runId. -
500 Internal server error during optimization. -
504 Gateway timeout: optimization exceeded the configured time limit. -

[Back to top] [Back to API list] [Back to Model list] [Back to README]

get_run_solution

Solution get_run_solution(run_id)

Retrieve the solution of a run (blocks until complete).

Blocks the connection until the optimization identified by runId finishes, then returns the Solution payload only, omitting full optimization metadata. Returns 404 if the runId is unknown or the run has already completed.

Example

import touroptimizer_py_client
from touroptimizer_py_client.models.solution import Solution
from touroptimizer_py_client.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to http://localhost
# See configuration.py for a list of all supported configuration parameters.
configuration = touroptimizer_py_client.Configuration(
    host = "http://localhost"
)


# Enter a context with an instance of the API client
with touroptimizer_py_client.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = touroptimizer_py_client.OptimizationApi(api_client)
    run_id = 'run_id_example' # str | Run identifier returned by POST /api/v1/runs.

    try:
        # Retrieve the solution of a run (blocks until complete).
        api_response = api_instance.get_run_solution(run_id)
        print("The response of OptimizationApi->get_run_solution:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling OptimizationApi->get_run_solution: %s\n" % e)

Parameters

Name Type Description Notes
run_id str Run identifier returned by POST /api/v1/runs.

Return type

Solution

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status code Description Response headers
200 Optimization finished. Solution payload returned. -
404 No active run found for this runId. -
500 Internal server error during optimization. -
504 Gateway timeout: optimization exceeded the configured time limit. -

[Back to top] [Back to API list] [Back to Model list] [Back to README]

get_started_signal

bool get_started_signal(run_id)

Emits once the run has transitioned to the running state.

Returns a single boolean true when the optimizer for the given runId transitions to the running state. Useful for clients that want to begin subscribing to event streams only after the optimizer has actually started.

Example

import touroptimizer_py_client
from touroptimizer_py_client.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to http://localhost
# See configuration.py for a list of all supported configuration parameters.
configuration = touroptimizer_py_client.Configuration(
    host = "http://localhost"
)


# Enter a context with an instance of the API client
with touroptimizer_py_client.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = touroptimizer_py_client.OptimizationApi(api_client)
    run_id = 'run_id_example' # str | Run identifier returned by POST /api/v1/runs.

    try:
        # Emits once the run has transitioned to the running state.
        api_response = api_instance.get_started_signal(run_id)
        print("The response of OptimizationApi->get_started_signal:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling OptimizationApi->get_started_signal: %s\n" % e)

Parameters

Name Type Description Notes
run_id str Run identifier returned by POST /api/v1/runs.

Return type

bool

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status code Description Response headers
200 Optimization has started. -
404 No active run found for this runId. -

[Back to top] [Back to API list] [Back to Model list] [Back to README]

start_run

RunAcceptedResponse start_run(rest_optimization)

Start an optimization run and return a runId.

Starts a synchronous optimization and returns HTTP 202 with a runId. Intended for short optimizations that complete within a few minutes. The result connection will time out after 10 minutes. For long-running optimizations use POST /api/v1/jobs instead, which provides async job tracking without holding an HTTP connection open.

Example

import touroptimizer_py_client
from touroptimizer_py_client.models.rest_optimization import RestOptimization
from touroptimizer_py_client.models.run_accepted_response import RunAcceptedResponse
from touroptimizer_py_client.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to http://localhost
# See configuration.py for a list of all supported configuration parameters.
configuration = touroptimizer_py_client.Configuration(
    host = "http://localhost"
)


# Enter a context with an instance of the API client
with touroptimizer_py_client.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = touroptimizer_py_client.OptimizationApi(api_client)
    rest_optimization = touroptimizer_py_client.RestOptimization() # RestOptimization | 

    try:
        # Start an optimization run and return a runId.
        api_response = api_instance.start_run(rest_optimization)
        print("The response of OptimizationApi->start_run:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling OptimizationApi->start_run: %s\n" % e)

Parameters

Name Type Description Notes
rest_optimization RestOptimization

Return type

RunAcceptedResponse

Authorization

No authorization required

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

HTTP response details

Status code Description Response headers
202 Run accepted and started. Use the runId with the companion endpoints. -
401 Unauthorized: license not valid or element limit exceeded. -
500 Internal server error during optimization setup. -

[Back to top] [Back to API list] [Back to Model list] [Back to README]

stop_run

bool stop_run(run_id)

Stop an active optimization run gracefully.

Requests a graceful stop of the run identified by runId. The optimizer finishes its current iteration and emits the best result found so far, which is then returned by the blocking GET result endpoint. Returns 404 if the runId is unknown or already completed.

Example

import touroptimizer_py_client
from touroptimizer_py_client.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to http://localhost
# See configuration.py for a list of all supported configuration parameters.
configuration = touroptimizer_py_client.Configuration(
    host = "http://localhost"
)


# Enter a context with an instance of the API client
with touroptimizer_py_client.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = touroptimizer_py_client.OptimizationApi(api_client)
    run_id = 'run_id_example' # str | Run identifier returned by POST /api/v1/runs.

    try:
        # Stop an active optimization run gracefully.
        api_response = api_instance.stop_run(run_id)
        print("The response of OptimizationApi->stop_run:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling OptimizationApi->stop_run: %s\n" % e)

Parameters

Name Type Description Notes
run_id str Run identifier returned by POST /api/v1/runs.

Return type

bool

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status code Description Response headers
200 Stop signal accepted. The run will terminate shortly. -
404 No active run found for this runId. -

[Back to top] [Back to API list] [Back to Model list] [Back to README]

stream_errors

List[JOptOptimizationError] stream_errors(run_id)

SSE stream of optimization errors for a run.

Subscribe to receive error events for the run identified by runId. Errors indicate serious problems that may affect result quality.

Example

import touroptimizer_py_client
from touroptimizer_py_client.models.j_opt_optimization_error import JOptOptimizationError
from touroptimizer_py_client.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to http://localhost
# See configuration.py for a list of all supported configuration parameters.
configuration = touroptimizer_py_client.Configuration(
    host = "http://localhost"
)


# Enter a context with an instance of the API client
with touroptimizer_py_client.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = touroptimizer_py_client.OptimizationApi(api_client)
    run_id = 'run_id_example' # str | Run identifier returned by POST /api/v1/runs.

    try:
        # SSE stream of optimization errors for a run.
        api_response = api_instance.stream_errors(run_id)
        print("The response of OptimizationApi->stream_errors:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling OptimizationApi->stream_errors: %s\n" % e)

Parameters

Name Type Description Notes
run_id str Run identifier returned by POST /api/v1/runs.

Return type

List[JOptOptimizationError]

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: text/event-stream, application/json

HTTP response details

Status code Description Response headers
200 OK -
404 No active run found for this runId. -

[Back to top] [Back to API list] [Back to Model list] [Back to README]

stream_progress

List[JOptOptimizationProgress] stream_progress(run_id)

SSE stream of optimization progress for a run.

Subscribe to receive real-time progress updates for the run identified by runId. Each event contains the current progress percentage and timing information.

Example

import touroptimizer_py_client
from touroptimizer_py_client.models.j_opt_optimization_progress import JOptOptimizationProgress
from touroptimizer_py_client.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to http://localhost
# See configuration.py for a list of all supported configuration parameters.
configuration = touroptimizer_py_client.Configuration(
    host = "http://localhost"
)


# Enter a context with an instance of the API client
with touroptimizer_py_client.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = touroptimizer_py_client.OptimizationApi(api_client)
    run_id = 'run_id_example' # str | Run identifier returned by POST /api/v1/runs.

    try:
        # SSE stream of optimization progress for a run.
        api_response = api_instance.stream_progress(run_id)
        print("The response of OptimizationApi->stream_progress:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling OptimizationApi->stream_progress: %s\n" % e)

Parameters

Name Type Description Notes
run_id str Run identifier returned by POST /api/v1/runs.

Return type

List[JOptOptimizationProgress]

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: text/event-stream, application/json

HTTP response details

Status code Description Response headers
200 OK -
404 No active run found for this runId. -

[Back to top] [Back to API list] [Back to Model list] [Back to README]

stream_status

List[JOptOptimizationStatus] stream_status(run_id)

SSE stream of optimization status messages for a run.

Subscribe to receive status lifecycle events for the run identified by runId (e.g. STARTED, RUNNING, FINISHED).

Example

import touroptimizer_py_client
from touroptimizer_py_client.models.j_opt_optimization_status import JOptOptimizationStatus
from touroptimizer_py_client.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to http://localhost
# See configuration.py for a list of all supported configuration parameters.
configuration = touroptimizer_py_client.Configuration(
    host = "http://localhost"
)


# Enter a context with an instance of the API client
with touroptimizer_py_client.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = touroptimizer_py_client.OptimizationApi(api_client)
    run_id = 'run_id_example' # str | Run identifier returned by POST /api/v1/runs.

    try:
        # SSE stream of optimization status messages for a run.
        api_response = api_instance.stream_status(run_id)
        print("The response of OptimizationApi->stream_status:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling OptimizationApi->stream_status: %s\n" % e)

Parameters

Name Type Description Notes
run_id str Run identifier returned by POST /api/v1/runs.

Return type

List[JOptOptimizationStatus]

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: text/event-stream, application/json

HTTP response details

Status code Description Response headers
200 OK -
404 No active run found for this runId. -

[Back to top] [Back to API list] [Back to Model list] [Back to README]

stream_warnings

List[JOptOptimizationWarning] stream_warnings(run_id)

SSE stream of optimization warnings for a run.

Subscribe to receive warning events for the run identified by runId. Warnings indicate non-fatal issues such as unserviceable nodes or soft constraint violations.

Example

import touroptimizer_py_client
from touroptimizer_py_client.models.j_opt_optimization_warning import JOptOptimizationWarning
from touroptimizer_py_client.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to http://localhost
# See configuration.py for a list of all supported configuration parameters.
configuration = touroptimizer_py_client.Configuration(
    host = "http://localhost"
)


# Enter a context with an instance of the API client
with touroptimizer_py_client.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = touroptimizer_py_client.OptimizationApi(api_client)
    run_id = 'run_id_example' # str | Run identifier returned by POST /api/v1/runs.

    try:
        # SSE stream of optimization warnings for a run.
        api_response = api_instance.stream_warnings(run_id)
        print("The response of OptimizationApi->stream_warnings:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling OptimizationApi->stream_warnings: %s\n" % e)

Parameters

Name Type Description Notes
run_id str Run identifier returned by POST /api/v1/runs.

Return type

List[JOptOptimizationWarning]

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: text/event-stream, application/json

HTTP response details

Status code Description Response headers
200 OK -
404 No active run found for this runId. -

[Back to top] [Back to API list] [Back to Model list] [Back to README]