Cloud Pendulum documentation
This is the documentation for the Cloud Pendulum system.
Client
- class cloudpendulumclient.client.Client
Client interface for communicating with the Cloud Pendulum Server. All methods send requests to the server to perform some action or retrieve some data.
Experiments are started using the start_experiment function. It will return a session token which will be required in all subsequent requests relating to that experiment session. The session will expire automatically after the requested_time has passed. The session will expire prematurely if no request were sent to the server within 2 seconds, or if the user sent a stop_experiment request.
If a request fails for any reason, a RuntimeError will be raised.
- __init__()
- start_experiment(user_token: str, experiment_type: str, experiment_time: float, preparation_time: float = 0.0, record: bool = False, initial_position: None | list[float] = None, disturbances: None | str | Disturbance | list[str | Disturbance] = None, cell_id: None | int = None, timeout: float | None = None) tuple[str, str]
Request to reserve a cell for some time to perform an experiment. This request will block until the server is able to allocate an appropriate cell to the client.
- Parameters:
user_token – A token for authenticating the user sending the request.
experiment_type – Determines the type of experiment to run on the cell when the reservation is accepted. Determines the type of cell that will be used.
experiment_time – The number of seconds to run the experiment for. The cell will be reserved for experiment_time + preparation_time seconds.
preparation_time – The number of seconds to wait after reserving a cell before starting the experiment. This could be useful to give you some time to open the livestream before the experiment starts.
record – Whether or not to record the experiment.
initial_position – The initial position from which the system should start at the beginning of the experiment. The list should only constain position values, not the full state with velocity included.
disturbances – Disturbances applied during the experiment. Can be either a string s.a. ‘double_pendulum_default’ giving a fixed sequence, or a user-defined list of disturbances as by the API.
cell_id – The id of a specific cell to reserve. Defaults to None, which means that any available cell will be booked.
timeout – Maximum amount of time to wait on queue before timing out
- Returns:
The session token for the experiment, and the livestream url for viewing the experiments camera feed. The session token will be required in all future requests to the server related to this experiment.
- stop_experiment(session_token: str) str
Stop the experiment corresponding to the given session token
- Parameters:
session_token – The session token returned by start_experiment.
- Returns:
The download url for the experiment recording if it was requested, otherwise None.
- get_user_info(user_token: str) UserInfo
Get all the info about the user with the provided user_token.
- Parameters:
user_token – The user token corresponding to the user we want to look up information about.
- Returns:
The user info.
- get_actuator_info(session_token: str) list[Actuator]
Get information about the actuators for the experiment currently running with the specified session token.
- Parameters:
session_token – The session token returned by start_experiment.
- Returns:
A list of Actuator.
- get_position(session_token: str) float | list[float]
Get the positions of the actuators in the cell running the experiment with the given session token.
- Parameters:
session_token – The session token returned by start_experiment.
- Returns:
The position of the actuators.
- get_velocity(session_token: str) float | list[float]
Get the velocity of the actuators in the cell running the experiment with the given session token.
- Parameters:
session_token – The session token returned by start_experiment.
- Returns:
The velocities of the actuators.
- get_torque(session_token: str) float | list[float]
Get the torque of the actuators in the cell running the experiment with the given session token.
- Parameters:
session_token – The session token returned by start_experiment.
- Returns:
The torques of the actuators.
- set_position(positions: list[float | None] | float, session_token: str)
Set the target positions for the actuators in the cell running the experiment with the given session token.
- Parameters:
positions – The target positions for the actuators. If None is supplied for an actuator, it is ignored. A single number can be supplied for experiments that only use a single motor.
session_token – The session token returned by start_experiment.
- Raises:
CloudPendulumException – If a limit violation has been reached on any of the actuators during this session.
- set_velocity(velocities: list[float | None] | float, session_token: str)
Set the target velocities for the actuators in the cell running the experiment with the given session token.
- Parameters:
velocities – The target velocities for the actuators. If None is supplied for an actuator, it is ignored. A single number can be supplied for experiments that only use a single motor.
session_token – The session token returned by start_experiment.
- Raises:
CloudPendulumException – If a limit violation has been reached on any of the actuators during this session.
- set_torque(torques: list[float | None] | float, session_token: str)
Set the target torques for the actuators in the cell running the experiment with the given session token.
- Parameters:
torques – The target torques for the actuators. If None is supplied for an actuator, it is ignored. A single number can be supplied for experiments that only use a single motor.
session_token – The session token returned by start_experiment.
- Raises:
CloudPendulumException – If a limit violation has been reached on any of the actuators during this session.
- set_impedance_controller_params(kp: float | list[float | None], kd: float | list[float | None], session_token: str)
Set the impedance controller parameters of the actuator in the cell running the experiment with the given session token.
- Parameters:
kp – Displacement gain for each motor. Applies to all motors if a single number is supplied.
kd – Damping coefficient for each motor. Applies to all motors if a single number is supplied.
session_token – The session token returned by start_experiment.
- Raises:
CloudPendulumException – If a limit violation has been reached on any of the actuators during this session.
- set_safety_limits(limits: list[SafetyLimits], session_token: str) bool
Set the safety limits for a session.
- Parameters:
limits – The new safety limits to set. They must more more restrictive than the default limits set for the current experiment type.
- Returns:
True if the limits were updated successfully, False otherwise.
- Raises:
CloudPendulumException – If a limit violation has been reached on any of the actuators during this session.
- start_gym(user_token: str, gym_time: float, cells: list[CellType | int]) str
Request to reserve some number of cells for some time to perform multiple experiments. This request will block until the client is able to allocate an appropriate cell to the client.
- Parameters:
user_token – A token for authenticating the user sending the request.
gym_time – The number of seconds to reserve the cells for.
cells – Determines the cells to reserve. For each CellType entry in this list, a cell of that type will be reserved. For each int entry in the list, the cell with that id will be reserved.
- Returns:
The gym token, which will be used in the start_experiment requests related to this gym session.
- stop_gym(gym_token: str)
Stop the gym session corresponding to the given gym token
- Parameters:
gym_token – The gym token returned by start_gym.
- start_episode(gym_token: str, experiment_type: str, episode_time: float, preparation_time: float = 0.0, record: bool = False, initial_position: None | list[float] = None, disturbances: list | None = None, cell_id: None | int = None, timeout: float | None = None) tuple[str, str]
Request to reserve a cell owned by the specified gym for some time to perform an experiment. This request will block until the server is able to allocate an appropriate cell (from among the cells owned by the gym) to the client.
- Parameters:
gym_token – A token for authenticating the request, and for specifying which gym session to reserve the cell from.
experiment_type – Determines the type of experiment to run on the cell when the reservation is accepted. Determines the type of cell that will be used.
episode_time – The number of seconds to run the experiment for. The cell will be reserved for episode_time + preparation_time seconds.
preparation_time – The number of seconds to wait after reserving a cell before starting the experiment. This could be useful to give you some time to open the livestream before the experiment starts.
record – Whether or not to record the experiment.
initial_position – The initial position from which the system should start at the beginning of the experiment. The list should only constain position values, not the full state with velocity included.
cell_id – The id of a specific cell to reserve. Defaults to None, which means that any available cell will be booked.
timeout – Maximum amount of time to wait on queue before timing out
- Returns:
The session token for the episode, and the livestream url for viewing the episodes camera feed. The session token will be required in all future requests to the server related to this episode.
- stop_episode(session_token: str) str
- get_logs(session_token: str) str
- get_cells(user_token: str) list[ClientCellInfo]
Get info about all the cells active on the system.
- Parameters:
user_token – A user token for authenticating the request
- Returns:
A list of ClientCellInfo
API
|