Mech Gym Environment

Mech follows the gym.Env interface.

The Mech Gym environment is a custom environment designed for path synthesis of linkage systems, and it keeps track of various aspects of the linkage throughout the generation process. This includes the revolute joint locations for all time steps, the edges between revolute joints, the set of scaffold nodes, all action combinations, the goal trajectory, the distance of the coupler to the goal, the reward, and many other things.

Despite the complexity of the Mech Gym environment, it provides all the main functionality of an OpenAI Gym Env, with additional methods that can be useful. The environment should be designed as several classes, but during development, it was easier to keep everything in one class for simplicity. I hope to refactor this in the future.

Usage

Create an instance of the Mechanism environment:

Mech(**env_kwargs)

where env_kwargs is a dictionary of keyword arguments to pass to the environment. The following keyword arguments are supported:

Methods

class linkage_gym.envs.Mech.Mech(max_nodes, bound, resolution, sample_points, feature_points, node_positions=None, edges=None, goal=None, normalize=True, self_loops=False, use_node_type=False, seed=None, fixed_initial_state=False, ordered_distance=False, constraints=[], min_nodes=5, debug=False, distance_metric='sqeuclidean')

Bases: Env

Custom Environment that follows gym interface

active_cycles()

Returns all the active loops in the linkage graph

Returns

all cycles in linkage graph NOTE: this includes cycles with 3 nodes which are not valid loops

Return type

list

add_edge(id0, id1)

Add edge to linkage graph

Parameters

• id0 (int) – index of node 0

• id1 (int) – index of node 1

add_node(node_pos)

Add node to the linkage graph

Parameters

node_pos (Nd.Array) – initial position of revolute joint Shape: (2, )

apply_random_action()

Applies a random valid action to the current environment

Returns

Observation, Reward, Done, Info

Return type

(Nd.Array, float, bool, dict)

clear_best_desings()

Clears self.best_designs

close()

Close environment

coords_to_pix(x)

Helper function for self.render converting coordinates to pixels

Parameters

x (Nd.Array) – coordinates Shape: (2, n)

Returns

pixel locations Shape: (2, n)

Return type

Nd.Array

coupler_traj(normalize=True, scale=None, shift=None)

Return the coupler node trajectory

Parameters

• normalize (bool, optional) – Normalized curve. Defaults to True.

• scale (float, optional) – scaling factor. Defaults to None.

• shift (Nd.Array, optional) – x,y shift for all points. Defaults to None.

Returns

coupler trajectory

Return type

Nd.Array

dfs(visited, edges, node, known_joints)

Helper function for depth first search

Parameters

• visited (list) – visited nodes

• edges (set) – set of edges

• node (int) – node index

• known_joints (list) – known joint trajectories

get_active_nodes()

Helper function to get all known nodes that contribute to coupler trajectory

Returns

node indexes that are used for coupler FK, edges that are useful for linkage graph

Return type

(list, set)

get_distance(scale=None, shift=None)

Distance between the coupler trajectory and the goal

Parameters

• scale (float, optional) – scaling factor for coupler trajectory. Defaults to None.

• shift (Nd.Array, optional) – shifting vector for coupler trajectory. Defaults to None.

Returns

distance

Return type

float

get_edge_lengths()

Helper function to return all the edge lengths

Returns

Lengths of each edge Shape: (e, )

Return type

Nd.Array

get_edge_mask(id0, id1)

Valid scaffold node locations for adding to Assur 0DOF linkage to node0 and node1

Parameters

• id0 (int) – index of node 0

• id1 (int) – index of node 1

Returns

valid scaffold nodes for adding to linkage graph

Return type

Nd.Array

get_edges(limit=None)

Helper function to return all the edges in the current linkage graph

Parameters

limit (int, optional) – edges between nodes bellow a particular index. Defaults to None.

Returns

Array of edge index pairs Shape: (e, 2) [id0, id1]

Return type

Nd.Array

get_observation()

Observation of current linkage state

Returns

[X ((Node_features)*max_nodes), adj (max_nodes*max_nodes), mask (max_nodes), action_mask (number_of_actions)] flattened

Return type

Nd.Array

get_valid_env(bar_type=None)

Generate random valid linkage graph

Returns

is valid

Return type

bool

is_valid()

Checks that linkage graph is valid

Returns

linkage graph is valid

Return type

bool

metadata = {'render_fps': 2, 'render_modes': ['human', 'rgb_array']}

number_of_active_nodes()

Helper function returns number of active nodes

Returns

number of active nodes in linkage graph

Return type

int

number_of_cycles()

Number of active linkage graph loops

Returns

number of active linkage graph loops NOTE: this excludes loops of 3 nodes (also known as triads as they are not useful)

Return type

int

number_of_edges()

Helper function returns the number of edges that make up the current linkage graph

Returns

number of edges

Return type

int

number_of_nodes()

Helper function returns number of nodes currently in the linkage graph

Returns

number of nodes

Return type

int

paper_plotting(show=False, show_goal=True, show_coupler=True, show_obj=True)

Helper function for plotting figures used in paper

Parameters

• show (bool, optional) – show the plot. Defaults to False.

• show_goal (bool, optional) – plot the goal on figure. Defaults to True.

• show_coupler (bool, optional) – plot the coupler curve on figure. Defaults to True.

• show_obj (bool, optional) – add objective value of linkage to figure. Defaults to True.

Returns

the figure object

Return type

Matplotlib.fig

plot_graph(plot_paths=False, plot_coupler=True, filename=None, coupler_idx=None)

Helper function to visualize linkage graph

Parameters

• plot_paths (bool, optional) – plot revolute joint trajectories. Defaults to False.

• plot_coupler (bool, optional) – plot coupler joint trajectory. Defaults to True.

• filename (str, optional) – filename to save figure. Defaults to None.

• coupler_idx (int, optional) – index of coupler index or other node that you want to be known as the coupler. Defaults to None.

Returns

figure

Return type

Matplotlib.fig

prune()

Prune linkage graph of unnecessary revolute joints

random_4_bar(edges, bar_type=None)

Random valid n bar linakge NOTE: not really N_bar, based on edges input

Parameters

• edges (Nd.Array) – set of edges Shape: (e, 2)

• n (int) – number of revolute joints

render(mode='human')

Render the linkage being generated

Parameters

mode (str, optional) – visualization mode. Defaults to “human”.

Raises

DependencyNotInstalled – needs pygame

Returns

successful

Return type

bool

reset()

Reset the environment to a root linkage

Returns

observation of the linkage (x, adj, mask, action_mask) flattened

Return type

Nd.Array

satisfy_constraints()

Checks if linkage graph satisfies the constraints

Returns

satifies

Return type

bool

seed(seed=None)

Set the seed for gym env

Parameters

seed (int, optional) – seed used for gym env. Defaults to None.

Returns

the seed value

Return type

int

step(action)

Update linkage graph with new action

Parameters

action (int) – index of action

Returns

Observation, Reward, Done, Info

Return type

(Nd.Array, float, bool, dict)

update_best_designs()

Update set of best designs of various linakge graph topologies

update_fixed_paths(fixed_node_pos)

Update self.paths for fixed revolute joints (DEPRECATED)

Parameters

fixed_node_pos (Nd.Array) – Vector of initial position of fixed nodes Shape: (n, 2)

update_paths(unknown_joints=None)

Update self.paths

Parameters

unknown_joints (list, optional) – node indexes that are not known or want to be calculated. Defaults to None.