| Name | cuopt-sh-client JSON |
| Version |
24.11.1
JSON |
| download |
| home_page | None |
| Summary | A Python client and command-line |
| upload_time | 2024-11-14 18:06:27 |
| maintainer | None |
| docs_url | None |
| author | NVIDIA Corporation |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# cuOpt Self-hosted Service Python Client
The cuOpt Self-hosted Service Python Client is a Python interface to enable access to NVIDIA cuOpt running on user-managed hardware.
Install `cuopt-sh-client` via pip
```bash
$ pip install .
```
## Run client using the CLI
After installation, the command-line utility can be accessed using
```bash
$ cuopt_sh cuopt_problem_data.json
```
If a problem times out, a request id will be returned. The id may be
passed back to the CLI to re-poll as shown. This may be done any number
of times until a result is returned.
```bash
$ cuopt_sh cuopt_problem_data.json
Request timed out.
Re-check the status with the following command:
cuopt_sh '{"reqId": "78238a58-d052-40b4-8dae-852be8f7906e"}'
$ cuopt_sh '{"reqId": "78238a58-d052-40b4-8dae-852be8f7906e"}'
{'response': ...}
```
### List of Arguments:
Check the help with 'cuopt_sh -h' for more detailed information.
data: cuOpt problem data file or a request id to repoll. If the -f option is used, this indicates the path of a file accessible to the server.
-f: Indicates that the DATA argument is the relative path of a cuOpt data file under the server's data directory.
-o: Override the default name of the result file if the server has been configured with a results directory.
-pt: Number of seconds to poll for a result before timing out and returning a request id to re-query. Defaults to 120.
-i: Host address of the cuOpt server (default 0.0.0.0)
-p: Port of the cuOpt server (default 5000)
-s: Use ssl (default False)
-c: Path to self signed certificates only, skip for standard certificates (default "")
-l: Log level (critical,error,warning,info,debug)
-ov: If set, only validates input
### Best practice: Using the local data file options (-f and -o)
Data describing a cuOpt problem can be quite large, and performance in most cases will be much better if the server can read files from its local filesystem instead of receiving them over HTTP.
To use this feature do the following:
* Configure the server to use a local data directory [(see below)](#configuring-the-cuopt-server-for-the-local-file-feature)
* Write the cuOpt data file to the server's local data directory. The file may be at the root of the data directory, or it may be placed at a path somewhere under the data directory.
* Specify the filename using the -f option to the cuOpt CLI. Give the path of the data file relative to the root of the server's local data directory.
Example:
```bash
# Copy the file to the server's data directory with scp (or some other mechanism)
$ scp cuopt_problem_data.json my_server:/path/of/cuOpt/data/directory/
# Indicate to the CLI that the data is in the server's local data directory with the name 'cuopt_problem_data.json'. Note that a relative path is used.
$ cuopt_sh -f cuopt_problem_data.json
```
The cuOpt results are usually much smaller than the input data and can easily be returned over HTTP. However, it may also be convenient to have results
written to output files as well. To use this feature do the following:
* Configure the server to use a local results directory and set the result size threshold for writing the results to disk [(see below)](#configuring-the-cuopt-server-for-the-local-file-feature)
* Use the -o option to specify a specific name for the result file, or let the server use a default name.
* Read the result from the file indicated in cuOpt's response.
Example:
```bash
$ cuopt_sh -f cuopt_problem_data.json
{'result_file': 'cuopt_problem_data.json.result'}
$ scp my_server:/path/of/cuOpt/results/directory/cuopt_problem_data.json.result .
```
### Data compression
The cuOpt server can accept data that has been compressed with the Python *msgpack* library or the Python *zlib* library.
For the highest efficiency, it is recommended that JSON data be generated with Python and written to a file using msgpack.
However, if the data is not written with msgpack, it can still be compressed later using msgpack or zlib, or left uncompressed.
## Run client directly from Python
### Initialize the CuOptServiceSelfHostClient with optional ip, port, and use_ssl args
```bash
from cuopt_sh_client import CuOptServiceSelfHostClient
cuopt_service_client = CuOptServiceSelfHostClient(ip, port)
```
### Get optimized routes
To submit a cuOpt data file over HTTP
```bash
# Send cuOpt data over HTTP
# Data may be the path to a file OR a dictionary containing
# a cuOpt problem
optimized_routes = cuopt_service_client.get_optimized_routes(
path_to_cuopt_problem_data
)
```
To specify a data file that is located on the server in the server's data directory
```bash
# Tell the cuOpt server that the data is in its local data directory
optimized_routes = cuopt_service_client.get_optimized_routes(
relative_path_under_servers_data_directory, filepath = True
)
```
The problem data file should contain a JSON object with the following details
cost_waypoint_graph_data
travel_time_waypoint_graph_data
cost_matrix_data
travel_time_matrix_data
fleet_data
task_data
solver_config
An example data file 'cuopt_problem_data.json' is included with this client.
For more details see https://docs.nvidia.com/cuopt/user-guide/serv-api.html
## Configuring the cuOpt Server for the Local File Feature
By default, the local file feature is not enabled in the cuOpt server. To configure the feature, set the environment variables described below in the server's container environment.
### Environment variables
To enable reading of cuOpt data files from the local filesystem, set the following
* CUOPT_DATA_DIR: the absolute path of a directory in the cuOpt server's container environment. Typically this path is the mount point for a volume that exists outside of the container.
To enable writing of cuOpt data files to the local filesystem, set
* CUOPT_RESULT_DIR: the absolute path of a directory in the cuOpt server's container environment. Typically this path is the mount point for a volume that exists outside of the container.
* CUOPT_MAX_RESULT: the maximum size in kilobytes of a result that cuOpt will return over HTTP. To have all results written to disk, set this value to 0. The default is 250.
* CUOPT_RESULT_MODE: the Linux file mode (as with the *chmod* command) to apply to result files created by cuOpt. The default is 644.
### Docker example
In this example, we run the image *cuoptimage* and mount the local directories *./data* and *./results* on the container at */cuopt_data* and */cuopt_resulst* respectively. We set the environment variables to tell cuOpt where the data and results directories are, and to write all results to files instead of HTTP (CUOPT_MAX_RESULT=0).
```bash
$ docker run --rm --gpus=all --network=host -v `pwd`/data:/cuopt_data -v `pwd`/results:/cuopt_results -e CUOPT_DATA_DIR=/cuopt_data -e CUOPT_RESULT_DIR=/cuopt_results -e CUOPT_MAX_RESULT=0 -it cuoptimage
```
### Directory permissions
The data and results directories mounted on the cuOpt container need to be readable and writable by the container user, and also have the execute permission set.
If they are not, the container will print an error message and exit. Be careful to set permissions correctly on those directories before running the cuOpt server.
When running cuOpt with docker and using the default container user:
* the cuOpt data directory should be readable and executable by group 0 (ie the *root* group)
* the cuOpt results directory should be writable and executable by group 0
When running cuOpt with docker and using the *--user* flag to set only the UID:
* the cuOpt data directory should be readable and executable by group 0 or the specified UID
* the cuOpt results directory should be writable and executable by group 0 or the specified UID
When running cuOpt with docker and using the *--user* flag to set both the UID and GID:
* the cuOpt data directory should be readable and executable by the specified UID or the specified GID
* the cuOpt results directory should be writable and executable by the specified UID or the specified GID
Raw data
{
"_id": null,
"home_page": null,
"name": "cuopt-sh-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "NVIDIA Corporation",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/9a/15/0a4fe9497543ac5bfc88d1b89f9969fc3d7ac7b5dfd538753bf446d73831/cuopt_sh_client-24.11.1.tar.gz",
"platform": null,
"description": "# cuOpt Self-hosted Service Python Client\nThe cuOpt Self-hosted Service Python Client is a Python interface to enable access to NVIDIA cuOpt running on user-managed hardware.\n\nInstall `cuopt-sh-client` via pip\n```bash\n$ pip install .\n```\n\n## Run client using the CLI\nAfter installation, the command-line utility can be accessed using\n```bash\n$ cuopt_sh cuopt_problem_data.json\n```\n\nIf a problem times out, a request id will be returned. The id may be\npassed back to the CLI to re-poll as shown. This may be done any number\nof times until a result is returned.\n```bash\n$ cuopt_sh cuopt_problem_data.json\nRequest timed out.\nRe-check the status with the following command:\ncuopt_sh '{\"reqId\": \"78238a58-d052-40b4-8dae-852be8f7906e\"}'\n\n$ cuopt_sh '{\"reqId\": \"78238a58-d052-40b4-8dae-852be8f7906e\"}'\n{'response': ...}\n```\n\n### List of Arguments:\nCheck the help with 'cuopt_sh -h' for more detailed information.\n\n data: cuOpt problem data file or a request id to repoll. If the -f option is used, this indicates the path of a file accessible to the server.\n -f: Indicates that the DATA argument is the relative path of a cuOpt data file under the server's data directory.\n -o: Override the default name of the result file if the server has been configured with a results directory.\n\t-pt: Number of seconds to poll for a result before timing out and returning a request id to re-query. Defaults to 120.\n -i: Host address of the cuOpt server (default 0.0.0.0)\n -p: Port of the cuOpt server (default 5000)\n -s: Use ssl (default False)\n -c: Path to self signed certificates only, skip for standard certificates (default \"\") \n -l: Log level (critical,error,warning,info,debug)\n\t-ov: If set, only validates input\n\n### Best practice: Using the local data file options (-f and -o)\n\nData describing a cuOpt problem can be quite large, and performance in most cases will be much better if the server can read files from its local filesystem instead of receiving them over HTTP.\nTo use this feature do the following:\n\n* Configure the server to use a local data directory [(see below)](#configuring-the-cuopt-server-for-the-local-file-feature)\n* Write the cuOpt data file to the server's local data directory. The file may be at the root of the data directory, or it may be placed at a path somewhere under the data directory.\n* Specify the filename using the -f option to the cuOpt CLI. Give the path of the data file relative to the root of the server's local data directory.\n\nExample:\n\n```bash\n# Copy the file to the server's data directory with scp (or some other mechanism)\n$ scp cuopt_problem_data.json my_server:/path/of/cuOpt/data/directory/\n\n# Indicate to the CLI that the data is in the server's local data directory with the name 'cuopt_problem_data.json'. Note that a relative path is used.\n$ cuopt_sh -f cuopt_problem_data.json\n```\n\nThe cuOpt results are usually much smaller than the input data and can easily be returned over HTTP. However, it may also be convenient to have results\nwritten to output files as well. To use this feature do the following:\n\n* Configure the server to use a local results directory and set the result size threshold for writing the results to disk [(see below)](#configuring-the-cuopt-server-for-the-local-file-feature)\n* Use the -o option to specify a specific name for the result file, or let the server use a default name.\n* Read the result from the file indicated in cuOpt's response.\n\nExample:\n\n```bash\n$ cuopt_sh -f cuopt_problem_data.json\n{'result_file': 'cuopt_problem_data.json.result'}\n\n$ scp my_server:/path/of/cuOpt/results/directory/cuopt_problem_data.json.result .\n```\n\n### Data compression\n\nThe cuOpt server can accept data that has been compressed with the Python *msgpack* library or the Python *zlib* library.\nFor the highest efficiency, it is recommended that JSON data be generated with Python and written to a file using msgpack.\nHowever, if the data is not written with msgpack, it can still be compressed later using msgpack or zlib, or left uncompressed.\n\n## Run client directly from Python\n### Initialize the CuOptServiceSelfHostClient with optional ip, port, and use_ssl args\n\n```bash\n\tfrom cuopt_sh_client import CuOptServiceSelfHostClient\n cuopt_service_client = CuOptServiceSelfHostClient(ip, port)\n```\n\n### Get optimized routes\n\nTo submit a cuOpt data file over HTTP\n\n```bash\n # Send cuOpt data over HTTP\n\t# Data may be the path to a file OR a dictionary containing\n\t# a cuOpt problem\n optimized_routes = cuopt_service_client.get_optimized_routes(\n path_to_cuopt_problem_data\n )\n```\n\nTo specify a data file that is located on the server in the server's data directory\n\n```bash\n # Tell the cuOpt server that the data is in its local data directory\n optimized_routes = cuopt_service_client.get_optimized_routes(\n relative_path_under_servers_data_directory, filepath = True\n )\n```\n\nThe problem data file should contain a JSON object with the following details\n\n cost_waypoint_graph_data\n travel_time_waypoint_graph_data\n cost_matrix_data\n travel_time_matrix_data\n fleet_data\n task_data\n solver_config\n\nAn example data file 'cuopt_problem_data.json' is included with this client.\n\nFor more details see https://docs.nvidia.com/cuopt/user-guide/serv-api.html\n\n## Configuring the cuOpt Server for the Local File Feature\n\nBy default, the local file feature is not enabled in the cuOpt server. To configure the feature, set the environment variables described below in the server's container environment.\n\n### Environment variables\n \nTo enable reading of cuOpt data files from the local filesystem, set the following\n\n* CUOPT_DATA_DIR: the absolute path of a directory in the cuOpt server's container environment. Typically this path is the mount point for a volume that exists outside of the container.\n\nTo enable writing of cuOpt data files to the local filesystem, set\n\n* CUOPT_RESULT_DIR: the absolute path of a directory in the cuOpt server's container environment. Typically this path is the mount point for a volume that exists outside of the container.\n* CUOPT_MAX_RESULT: the maximum size in kilobytes of a result that cuOpt will return over HTTP. To have all results written to disk, set this value to 0. The default is 250.\n* CUOPT_RESULT_MODE: the Linux file mode (as with the *chmod* command) to apply to result files created by cuOpt. The default is 644.\n\n### Docker example\n\nIn this example, we run the image *cuoptimage* and mount the local directories *./data* and *./results* on the container at */cuopt_data* and */cuopt_resulst* respectively. We set the environment variables to tell cuOpt where the data and results directories are, and to write all results to files instead of HTTP (CUOPT_MAX_RESULT=0).\n\n```bash\n$ docker run --rm --gpus=all --network=host -v `pwd`/data:/cuopt_data -v `pwd`/results:/cuopt_results -e CUOPT_DATA_DIR=/cuopt_data -e CUOPT_RESULT_DIR=/cuopt_results -e CUOPT_MAX_RESULT=0 -it cuoptimage\n```\n\n### Directory permissions\n\nThe data and results directories mounted on the cuOpt container need to be readable and writable by the container user, and also have the execute permission set.\nIf they are not, the container will print an error message and exit. Be careful to set permissions correctly on those directories before running the cuOpt server.\n\nWhen running cuOpt with docker and using the default container user:\n\n* the cuOpt data directory should be readable and executable by group 0 (ie the *root* group)\n* the cuOpt results directory should be writable and executable by group 0\n\nWhen running cuOpt with docker and using the *--user* flag to set only the UID:\n\n* the cuOpt data directory should be readable and executable by group 0 or the specified UID\n* the cuOpt results directory should be writable and executable by group 0 or the specified UID\n\nWhen running cuOpt with docker and using the *--user* flag to set both the UID and GID:\n\n* the cuOpt data directory should be readable and executable by the specified UID or the specified GID\n* the cuOpt results directory should be writable and executable by the specified UID or the specified GID\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python client and command-line",
"version": "24.11.1",
"project_urls": {
"Homepage": "https://docs.nvidia.com/cuopt/overview.html",
"Source": "https://github.com/rapidsai/cuopt"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9a150a4fe9497543ac5bfc88d1b89f9969fc3d7ac7b5dfd538753bf446d73831",
"md5": "2abaff9c5d226a58925fabaf32371e47",
"sha256": "752fea4b0c9302bfe93cb1e7d2d94068bdca804261b25120be37df795a1b1cff"
},
"downloads": -1,
"filename": "cuopt_sh_client-24.11.1.tar.gz",
"has_sig": false,
"md5_digest": "2abaff9c5d226a58925fabaf32371e47",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 3572,
"upload_time": "2024-11-14T18:06:27",
"upload_time_iso_8601": "2024-11-14T18:06:27.281892Z",
"url": "https://files.pythonhosted.org/packages/9a/15/0a4fe9497543ac5bfc88d1b89f9969fc3d7ac7b5dfd538753bf446d73831/cuopt_sh_client-24.11.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-14 18:06:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rapidsai",
"github_project": "cuopt",
"github_not_found": true,
"lcname": "cuopt-sh-client"
}
