> For the complete documentation index, see [llms.txt](https://lexset-1.gitbook.io/lexset-seahaven/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lexset-1.gitbook.io/lexset-seahaven/manage-simulation/python-api-v3-beta/functions.md). # Methods A comprehensive list of available functions in the new API version! We have curated a robust collection of methods and tools designed to empower you, our valued users, to seamlessly integrate our API into your applications and projects. This section will provide you with a detailed overview of each function, its purpose, and sample use cases to help you navigate and make the most of the enhanced capabilities. Our aim is to ensure a smooth and efficient experience as you explore the various offerings of this updated API, unlocking new possibilities and optimizing your workflows. ## **get\_dataset\_id** This method retrieves the dataset ID(s) associated with the simulation ID(s) of the **simulation** object. ### **Example** ```python sim.get_dataset_id() ``` ### **Error Messages and Warnings** **Warning message:** ```python Simulation ID(s) not set. Use the setSimulation_id method to set the simulationID. ``` This warning occurs when the **simulation\_id** attribute is not set before calling the **get\_dataset\_id** method. To resolve this warning, use the **setSimulation\_id** method to set the simulation ID(s) before calling the **get\_dataset\_id** method. **Error message:** ``` Unauthorized: 401 ``` This error occurs when the provided access token is invalid or has expired. To resolve this error, ensure that you are using a valid access token when initializing the **simulation** object. **Error message:** ``` getDataset_id() Error: ``` This error occurs when an unexpected HTTP status code is received from the server. To resolve this error, make sure the Lexset API is accessible and functioning properly, and ensure that the provided user and organization IDs are valid. By following the above example and explanation, you can successfully use the **get\_dataset\_id** method to retrieve the dataset ID(s) associated with the simulation ID(s). Make sure to set the **simulation\_id** attribute before calling this method and be aware of the possible error messages and warnings. ## **get\_organization\_simulations** This method retrieves a list of simulations for a given organization ID based on the specified state. ### **Arguments** * **state** (str): The state of the simulations to be retrieved. Valid states are "RUNNING", "QUEUED", "COMPLETED", and "CREATED". * **limit** (int, optional): The maximum number of simulations to return. Defaults to 100. ### **Example** ```python state = "COMPLETED" limit = 10 simulations = sim.get_organization_simulations(state, limit) #This will return JSON print(json.dumps(simulations, indent=4, sort_keys=True)) ``` ### **Error Messages and Warnings** **Error message:** ```python Invalid State: Valid States: RUNNING, COMPLETED, CREATED ``` This error occurs when the provided **state** argument is not valid. To resolve this error, use a valid state ("RUNNING", "QUEUED", "COMPLETED", or "CREATED") when calling the **get\_organization\_simulations** method. **Error message:** ```python Unauthorized: 401 ``` This error occurs when the provided access token is invalid or has expired. To resolve this error, ensure that you are using a valid access token when initializing the **simulation** object. **Error message:** ```python get_organization_simulations() Error: ``` This error occurs when an unexpected HTTP status code is received from the server. To resolve this error, make sure the Lexset API is accessible and functioning properly, and ensure that the provided user and organization IDs are valid. By following the above example and explanation, you can successfully use the **get\_organization\_simulations** method to retrieve a list of simulations for the given organization ID based on the specified state. Make sure to provide a valid state when calling this method and be aware of the possible error messages. ## **download** This method downloads the dataset associated with the **simulation** object's dataset ID(s) in parallel using multiple worker threads. The downloaded dataset is saved as a ZIP file. ### **Arguments** * **localPath** (str, optional): The local path where the downloaded dataset will be saved. If not provided, the dataset will be saved in the current working directory. Defaults to "NONE". * **workers** (int, optional): The number of worker threads to use for parallel downloading. Defaults to 2. ### **Example** ```python localPath = "downloads" workers = 4 sim.download(localPath, workers) ``` ### **Error Messages and Warnings** **Error message:** ```python No simulation associated with this object. Please set a simulation with the setSimulation_id method. ``` This error occurs when the **simulation\_id** attribute is not set before calling the **download** method. To resolve this error, use the **setSimulation\_id** method to set the simulation ID(s) before calling the **download** method. **Error message:** ```python Unauthorized: 401 ``` This error occurs when the provided access token is invalid or has expired. To resolve this error, ensure that you are using a valid access token when initializing the **simulation** object. **Error message:** ```python download() Error: ``` This error occurs when an unexpected HTTP status code is received from the server. To resolve this error, make sure the Lexset API is accessible and functioning properly, and ensure that the provided user and organization IDs are valid. **Error message:** ```python Simulation(s) not complete. Please wait for simulation to complete before downloading. ``` This error occurs when the simulation associated with the dataset is not complete. To resolve this error, wait for the simulation to complete before calling the **download** method. By following the above example and explanation, you can successfully use the **download** method to download the dataset associated with the **simulation** object's dataset ID(s). Make sure to set the **simulation\_id** attribute before calling this method and be aware of the possible error messages and warnings. ## **create\_simulation** This method creates a new simulation by sending a POST request to the Lexset API. It takes the configuration from a file and encodes it in Base64 format. ### **Arguments** * **simulationPath** (str): The path to the YAML configuration file for the simulation. * **simulationName** (str): The name of the simulation. * **description** (str): A brief description of the simulation. * **nodeCount** (int): The number of nodes requested for the simulation. * **numImages** (int): The number of images to be generated in the simulation. ### **Example** ```python simulationPath = "path/to/simulation_config.yaml" simulationName = "My Simulation" description = "A sample simulation" nodeCount = 5 numImages = 1000 sim.create_simulation(simulationPath, simulationName, description, nodeCount, numImages) ``` ### **Error Messages and Warnings** **Error message:** ```python Unauthorized: 401 ``` This error occurs when the provided access token is invalid or has expired. To resolve this error, ensure that you are using a valid access token when initializing the **simulation** object. **Error message:** ```python create_simulation() Error: ``` This error occurs when an unexpected HTTP status code is received from the server. To resolve this error, make sure the Lexset API is accessible and functioning properly, and ensure that the provided user and organization IDs are valid. By following the above example and explanation, you can successfully use the **create\_simulation** method to create a new simulation with the specified configuration, name, description, node count, and number of images. Make sure to be aware of the possible error messages and warnings. *** ## **delete\_simulation** This method deletes an existing simulation by sending a DELETE request to the Lexset API. It works with either a single simulation ID or a list of simulation IDs. ### **Example** ```python sim.delete_simulation() ``` ### **Error Messages and Warnings** **Error message:** ```python Unauthorized: 401 ``` This error occurs when the provided access token is invalid or has expired. To resolve this error, ensure that you are using a valid access token when initializing the **simulation** object. **Error message:** ```python delete_simulation() Error: ``` This error occurs when an unexpected HTTP status code is received from the server. To resolve this error, make sure the Lexset API is accessible and functioning properly, and ensure that the provided user and organization IDs are valid. By following the above example and explanation, you can successfully use the **delete\_simulation** method to delete an existing simulation or a list of simulations. Make sure to be aware of the possible error messages and warnings. ## **add\_file** This method uploads a user file to the Lexset API. The supported file types are **RELATIONSHIPS** and **COLORMAP**. ### **Parameters** * **location**: The path to the file that you want to upload. * **type**: The type of the file you are uploading. It can be either **RELATIONSHIPS** or **COLORMAP**. ### **Example** ```python sim.add_file("path/to/relationships_file.txt", type="RELATIONSHIPS") ``` ### **Error Messages and Warnings** **Error message:** ``` Please specify a file type, LIST_ALL, RELATIONSHIPS, or COLORMAP ``` This error occurs when the file type is not specified or set to "None". To resolve this error, provide a valid file type in the **type** parameter. **Error message:** ``` Unauthorized: 401 ``` This error occurs when the provided access token is invalid or has expired. To resolve this error, ensure that you are using a valid access token when initializing the **simulation** object. **Error message:** ``` add_file() Error: ``` This error occurs when an unexpected HTTP status code is received from the server. To resolve this error, make sure the Lexset API is accessible and functioning properly, and ensure that the provided user and organization IDs are valid. By following the above example and explanation, you can successfully use the **add\_file** method to upload a user file to the Lexset API. Make sure to be aware of the possible error messages and warnings. ## **active\_nodes** This method returns the number of active nodes in the user's simulations. ### **Example** ```python sim.active_nodes() ``` ### **Return Value** This method returns an integer value representing the number of active nodes. ### **Error Messages and Warnings** **Error message:** ``` Unauthorized: 401 ``` This error occurs when the provided access token is invalid or has expired. To resolve this error, ensure that you are using a valid access token when initializing the **simulation** object. **Error message:** ``` active_nodes() Error: ``` This error occurs when an unexpected HTTP status code is received from the server. To resolve this error, make sure the Lexset API is accessible and functioning properly, and ensure that the provided user and organization IDs are valid. By following the above example and explanation, you can successfully use the **active\_nodes** method to get the number of active nodes in the user's simulations. Make sure to be aware of the possible error messages and warnings. ## **start** This method starts the simulation(s) associated with the current **simulation** object. ### **Example** ```python sim.start() ``` ### **Return Value** This method returns a string value "success" when the simulation is successfully started. ### **Error Messages and Warnings** **Error message:** ``` Unauthorized: 401 ``` This error occurs when the provided access token is invalid or has expired. To resolve this error, ensure that you are using a valid access token when initializing the **simulation** object. **Error message:** ``` start() Error: ``` This error occurs when an unexpected HTTP status code is received from the server. To resolve this error, make sure the Lexset API is accessible and functioning properly, and ensure that the provided user and organization IDs are valid, and the simulation ID is correct. By following the above example and explanation, you can successfully use the **start** method to start the simulation(s) associated with the current **simulation** object. Make sure to be aware of the possible error messages and warnings. ## **dequeue** This method removes the simulation(s) associated with the current **simulation** object from the queue and sets it in a ready state. For more information on simulation states, please refer to the [simulation manager ](/lexset-seahaven/simulation-manager/simulation-manager.md)documentation. ### **Example** ```python sim.dequeue() ``` ### **Return Value** This method returns a string value "success" when the simulation is successfully started. ### **Error Messages and Warnings** **Error message:** ``` Unauthorized: 401 ``` This error occurs when the provided access token is invalid or has expired. To resolve this error, ensure that you are using a valid access token when initializing the **simulation** object. **Error message:** ``` start() Error: ``` This error occurs when an unexpected HTTP status code is received from the server. To resolve this error, make sure the Lexset API is accessible and functioning properly, and ensure that the provided user and organization IDs are valid, and the simulation ID is correct. By following the above example and explanation, you can successfully use the **start** method to start the simulation(s) associated with the current **simulation** object. Make sure to be aware of the possible error messages and warnings. ## **stop** This method stops the simulation(s) associated with the current **simulation** object. ### **Example** ```python sim.stop() ``` ### **Return Value** This method returns a string value "success" when the simulation is successfully stopped. ### **Error Messages and Warnings** **Error message:** ``` Unauthorized: 401 ``` This error occurs when the provided access token is invalid or has expired. To resolve this error, ensure that you are using a valid access token when initializing the **simulation** object. **Error message:** ``` stop() Error: ``` This error occurs when an unexpected HTTP status code is received from the server. To resolve this error, make sure the Lexset API is accessible and functioning properly, and ensure that the provided user and organization IDs are valid, and the simulation ID is correct. By following the above example and explanation, you can successfully use the **stop** method to stop the simulation(s) associated with the current **simulation** object. Make sure to be aware of the possible error messages and warnings. ## **get\_progress** This method retrieves the progress percentage of the simulation(s) associated with the current **simulation** object. ### **Example** ```python sim.get_progress() ``` ### **Return Value** This method returns a JSON object containing the progress percentage of the simulation(s) associated with the current **simulation** object. ### **Error Messages and Warnings** **Error message:** ``` Unauthorized: 401 ``` This error occurs when the provided access token is invalid or has expired. To resolve this error, ensure that you are using a valid access token when initializing the **simulation** object. **Error message:** ``` get_progress() Error: ``` This error occurs when an unexpected HTTP status code is received from the server. To resolve this error, make sure the Lexset API is accessible and functioning properly, and ensure that the provided user and organization IDs are valid, and the simulation ID is correct. **Warning message:** ``` Check simulation status with the get_status method. ``` This warning is displayed when the **get\_progress** method encounters an error. It suggests using the **get\_status** method to check the simulation status for further information. By following the above example and explanation, you can successfully use the **get\_progress** method to retrieve the progress percentage of the simulation(s) associated with the current **simulation** object. Make sure to be aware of the possible error messages and warnings. ## **get\_status** This method retrieves the status of the simulation(s) associated with the current **simulation** object, including whether the simulation(s) have started and whether they are complete. ### **Example** ```python sim.get_status() ``` ### **Return Value** This method returns a list of tuples containing the simulation ID, the completion status, and the started status of the simulation(s) associated with the current **simulation** object. ### **Error Messages and Warnings** **Error message:** ``` Unauthorized: 401 ``` This error occurs when the provided access token is invalid or has expired. To resolve this error, ensure that you are using a valid access token when initializing the **simulation** object. **Error message:** ``` get_status() Error: ``` This error occurs when an unexpected HTTP status code is received from the server. To resolve this error, make sure the Lexset API is accessible and functioning properly, and ensure that the provided user and organization IDs are valid, and the simulation ID is correct. By following the above example and explanation, you can successfully use the **get\_status** method to retrieve the status of the simulation(s) associated with the current **simulation** object. Make sure to be aware of the possible error messages and warnings. ## **gcp\_transfer** The **gcp\_transfer** method allows you to transfer the datasets generated by simulations to a Google Cloud Storage bucket. NOTE: [Please see the credentials documentation for more details.](/lexset-seahaven/manage-simulation/python-api-v3-beta/credentials.md)\ You must add your GCP credentials before you can use this feature. Please read the following instructions [here](/lexset-seahaven/manage-simulation/python-api-v3-beta/credentials.md). ### **Parameters** * **bucketName** (str): The name of the Google Cloud Storage bucket where the datasets will be transferred. ### **Example** ```python sim.gcp_transfer("your-gcs-bucket-name") ``` ### **Return Value** This method returns the parsed JSON response if the transfer is successful. If an error occurs, the method returns the HTTP status code. ### **Error Messages and Warnings** **Error message:** ``` Unauthorized: 401 ``` This error occurs when the provided access token is invalid or has expired. To resolve this error, ensure that you are using a valid access token when initializing the **simulation** object. **Error message:** ``` getDataset_id() Error: ``` This error occurs when an unexpected HTTP status code is received from the server. To resolve this error, make sure the Lexset API is accessible and functioning properly, and ensure that the provided user and organization IDs are valid, and the simulation ID is correct. To use the **gcp\_transfer** method, follow the example and explanation provided, and make sure to be aware of the possible error messages and warnings. This method will help you transfer the generated datasets to your Google Cloud Storage bucket.