pyphysim.cell package¶

Submodules¶

pyphysim.cell.cell module¶

Module that implements Cell and Cluster related classes.

class pyphysim.cell.cell.AccessPoint(pos: complex, ap_id: Optional[Union[str, int]] = None)[source]¶

Bases: pyphysim.cell.cell.Node

Access point class.

An access point acts as a transmitter to one of more users.

Parameters

pos (complex) – The central position of the cell in the complex grid.
ap_id (int, str, optional) – The AccessPoint ID. If not provided the access point won’t have an ID and its plot will shown a symbol at the access point location instead of the ID.

_plot_common_part(ax: Any) → None [source]¶

Common code for plotting the classes. Each subclass must implement a plot method in which it calls the command to plot the class shape followed by _plot_common_part.

Parameters: ax (A matplotlib axis) – The axis where the cell will be plotted.

add_user(new_user: pyphysim.cell.cell.Node, relative_pos_bool: bool = True) → None [source]¶

Associate a new user with the access point.

Parameters

new_user (Node) – The new user to be associated with the access point.
relative_pos_bool (bool) – Indicates it the position of the new_user is relative.

delete_all_users() → None [source]¶: Delete all users from the cell.

property num_users¶

Get method for the num_users property.

Returns: The number of users associated with the AccessPoint.
Return type: int

plot(ax: Optional[Any] = None) → None [source]¶

Plot the AccessPoint using the matplotlib library.

Parameters: ax (A matplotlib axis, optional) – The axis where the cell will be plotted. If not provided, a new figure (and axis) will be created.

property pos¶

Get the AccessPoint position.

Returns: The AccessPoint position.
Return type: complex

property users¶

Get method for the users property.

Returns: The users associated with the AccessPoint.
Return type: list[Node]

class pyphysim.cell.cell.Cell(pos: complex, radius: float, cell_id: Optional[Union[str, int]] = None, rotation: float = 0.0)[source]¶

Bases: pyphysim.cell.shapes.Hexagon, pyphysim.cell.cell.CellBase

Class representing an hexagon cell.

Parameters

pos (complex) – The central position of the cell in the complex grid.
radius (float) – The cell radius.
cell_id (str, int, optional) – The cell ID. If not provided the cell won’t have an ID and its plot will shown a symbol in cell center instead of the cell ID.
rotation (float, optional) – The rotation of the cell (regarding the cell center).

plot(ax: Optional[Any] = None) → None [source]¶

Plot the cell using the matplotlib library.

If an axes ‘ax’ is specified, then the shape is added to that axis. Otherwise a new figure and axis are created and the shape is plotted to that.

Parameters: ax (A matplotlib axis, optional) – The axis where the cell will be plotted. If not provided, a new figure (and axis) will be created.

class pyphysim.cell.cell.Cell3Sec(pos: complex, radius: float, cell_id: Optional[Union[str, int]] = None, rotation: float = 0.0)[source]¶

Bases: pyphysim.cell.cell.CellBase

Class representing a cell with 3 sectors.

Each sector corresponds to an hexagon.

Parameters

pos (complex) – The central position of the cell in the complex grid.
radius (float) – The cell radius. The sector radius will be equal to half the cell radius.
cell_id (str, int, optional) – The cell ID. If not provided the cell won’t have an ID and its plot will shown a symbol in cell center instead of the cell ID.
rotation (float, optional) – The rotation of the cell (regarding the cell center).

_calc_sectors_positions() → numpy.ndarray [source]¶

Calculates the positions of the sectors with the current rotation, center position and radius.

Returns: The positions of the 3 sectors.
Return type: np.ndarray

_get_vertex_positions() → numpy.ndarray [source]¶

Calculates the vertex positions ignoring any rotation and considering that the shape is at the origin (rotation and translation will be added automatically later).

Returns: vertex_positions – The positions of the vertexes of the shape.
Return type: np.ndarray

add_random_user_in_sector(sector: int, user_color: Optional[str] = None, min_dist_ratio: float = 0.0) → None [source]¶

Adds a user randomly located in the specified sector of the cell.

Parameters

sector (int) – The sector index. Can only be 1, 2 or 3.
user_color (str) – Color of the user’s marker.
min_dist_ratio (float) – Minimum allowed (relative) distance between the cell center and the generated random user. The value must be between 0 and 0.7.

add_random_users_in_sector(num_users: int, sector: int, user_color: Optional[str] = None, min_dist_ratio: float = 0.0) → None [source]¶

Add num_users users randomly in the specified sector of the cell

Parameters

num_users (int) – Number of users to be added to the sector.
sector (int) – The sector index. Can only be 1, 2 or 3.
user_color (str) – Color of the user’s marker.
min_dist_ratio (float) – Minimum allowed (relative) distance between the cell center and the generated random user. The value must be between 0 and 0.7.

plot(ax: Optional[Any] = None) → None [source]¶

Plot the cell using the matplotlib library.

If an axes ‘ax’ is specified, then the shape is added to that axis. Otherwise a new figure and axis are created and the shape is plotted to that.

Parameters: ax (A matplotlib axis, optional) – The axis where the cell will be plotted. If not provided, a new figure (and axis) will be created.

property pos¶

Get the Cell3Sec position.

Returns: The Cell3Sec position.
Return type: complex

property radius¶

Get the radius of the Cell3Sec object.

Returns: The radius of the Cell3Sec object.
Return type: float

property rotation¶

Get method for the rotation property.

Returns: The shape rotation.
Return type: float

property secradius¶

Get method for the secradius property.

The radius of a sector.

Returns: The radius of one sector of the Cell3Sec object.
Return type: float

class pyphysim.cell.cell.CellBase(pos: complex, radius: float, cell_id: Optional[Union[str, int]] = None, rotation: float = 0.0, **kw)[source]¶

Bases: pyphysim.cell.shapes.Shape, pyphysim.cell.cell.AccessPoint

Base class for all cell types.

A cell is an AccessPoint with a predefined shape, where the users associated with it are inside the shape.

Parameters

pos (complex) – The central position of the cell in the complex grid.
radius (float) – The cell radius.
cell_id (str, int, optional) – The cell ID. If not provided the cell won’t have an ID and its plot will shown a symbol in cell center instead of the cell ID.
rotation (float, optional) – The rotation of the cell (regarding the cell center).

static _validate_ratio(ratio: float) → float [source]¶

Return ratio if is valid, 1.0 if ratio is None, or throw an exception if it is not valid.

This is a helper method used in the add_border_user method implementation.

Parameters: ratio (float) – The ratio (a number between 0 and 1).
Returns: ratio – The valid ratio. If ratio parameter was ‘None’ then 1.0 will be returned.
Return type: float
Raises: ValueError – If ratio is not between 0 and 1.

add_border_user(angles: Union[float, Iterable[float]], ratio: Optional[Union[float, Iterable[float]]] = None, user_color: Optional[Union[str, Iterable[str]]] = None) → None [source]¶

Adds a user at the border of the cell, located at a specified angle (in degrees).

If the angles variable is an iterable, one user will be added for each value in angles. Also, in that case ration and user_color may also be iterable with the same length of angles in order to specify individual ratio and user_color for each angle.

Parameters

angles (float | list[float] | np.ndarray) – Angle(s) for which users will be added (may be a single number or an iterable).
ratio (float | list[float] | np.ndarray | None) – The ration (relative distance from cell center) for which users will be added (may be a single number or an iterable). If not specified the users will be added to the cell’s border at the angles specified in angles.
user_color (str | list[str], optional) – Color of the user’s marker.

Raises

ValueError – If the ratio is invalid (negative or greater than 1).

add_random_user(user_color: Optional[str] = None, min_dist_ratio: float = 0.0) → None [source]¶

Adds a user randomly located in the cell.

The variable user_color can be any color that the plot command and friends can understand. If not specified the default value of the node class will be used.

Parameters

user_color (str, optional) – Color of the user’s marker.
min_dist_ratio (float) – Minimum allowed (relative) distance between the cell center and the generated random user. The value must be between 0 and 0.7.

add_random_users(num_users: int, user_color: Optional[str] = None, min_dist_ratio: float = 0.0) → None [source]¶

Add num_users users randomly located in the cell.

Parameters

num_users (int) – Number of users to be added to the cell.
user_color (str, optional) – Color of the user’s marker.
min_dist_ratio (float) – Minimum allowed (relative) distance between the cell center and the generated random user. The value must be between 0 and 0.7.

add_user(new_user: pyphysim.cell.cell.Node, relative_pos_bool: bool = True) → None [source]¶

Adds a new user to the cell.

Parameters

new_user (Node) – The new user to be added to the cell.
relative_pos_bool (bool, optional (default to True)) – Indicates if the ‘pos’ attribute of the new_user is relative to the center of the cell or not.

Returns

Return type

None

Raises

ValueError – If the user position is outside the cell (the user won’t be added).

plot_border(ax: Optional[Any] = None) → None [source]¶

Plot the border of the cell.

If an axes ‘ax’ is specified, then the shape is added to that axis. Otherwise a new figure and axis are created and the shape is plotted to that.

Parameters: ax (A matplotlib axis, optional) – The axis where the cell will be plotted. If not provided, a new figure (and axis) will be created.

class pyphysim.cell.cell.CellSquare(pos: complex, side_length: float, cell_id: Optional[Union[str, int]] = None, rotation: float = 0.0)[source]¶

Bases: pyphysim.cell.shapes.Rectangle, pyphysim.cell.cell.CellBase

Class representing a ‘square’ cell.

Parameters

pos (complex) – The central position of the cell in the complex grid.
side_length (float) – The cell side length.
cell_id (str, int, optional) – The cell ID. If not provided the cell won’t have an ID and its plot will shown a symbol in cell center instead of the cell ID.
rotation (float, optional) – The rotation of the cell (regarding the cell center).

add_user(new_user: pyphysim.cell.cell.Node, relative_pos_bool: bool = True) → None [source]¶

Adds a new user to the cell.

Parameters

new_user (Node) – The new user to be added to the cell.
relative_pos_bool (bool, optional) – Indicates if the ‘pos’ attribute of the new_user is relative to the center of the cell or not.

Raises

ValueError – If the user position is outside the cell (the user won’t be added).

plot(ax: Optional[Any] = None) → None [source]¶

Plot the cell using the matplotlib library.

If an axes ‘ax’ is specified, then the shape is added to that axis. Otherwise a new figure and axis are created and the shape is plotted to that.

Parameters: ax (A matplotlib axis, optional) – The axis where the cell will be plotted. If not provided, a new figure (and axis) will be created.

class pyphysim.cell.cell.CellWrap(pos: complex, wrapped_cell: pyphysim.cell.cell.CellBase, include_users_bool: bool = False)[source]¶

Bases: pyphysim.cell.cell.CellBase

Class that wraps another cell.

Parameters

pos (complex) – The central position where the wrapped cell will be in the complex grid.
wrapped_cell (T <= CellBase) – The wrapped cell. It must be an object of some subclass of CellBase.
include_users_bool (bool) – Set to True if the users of the original cells should appear in the wrapped version.

_get_vertex_positions() → numpy.ndarray [source]¶

Calculates the vertex positions ignoring any rotation and considering that the shape is at the origin (rotation and translation will be added automatically later).

Returns: vertex_positions – The positions of the vertexes of the shape.
Return type: np.ndarray

property num_users¶

Get method for the num_users property.

Returns: The number of users associated with the AccessPoint.
Return type: int

plot(ax: Optional[Any] = None) → None [source]¶

Plot the shape using the matplotlib library.

Parameters: ax (A matplotlib ax, optional) – The ax where the shape will be plotted. If not provided, a new figure (and ax) will be created.

Notes

If an axes ‘ax’ is specified, then the shape is added to that axes. Otherwise a new figure and axes are created and the shape is plotted to that.

property radius¶

Get the radius of the CellWrap object.

Returns: The radius of the CellWrap object.
Return type: float

property rotation¶

Get the rotation of the CellWrap object.

Returns: The rotation of the CellWrap object.
Return type: float

property users¶

Get method for the users property.

Returns: The users associated with the AccessPoint.
Return type: list

class pyphysim.cell.cell.Cluster(cell_radius: float, num_cells: int, pos: complex = 0j, cluster_id: Optional[int] = None, cell_type: str = 'simple', rotation: float = 0.0)[source]¶

Bases: pyphysim.cell.shapes.Shape

Class representing a cluster of Hexagonal cells.

Valid cluster sizes are given by the formula \(N = i^2+i*j+j^2\) where i and j are integer numbers. The allowed values in the Cluster class are summarized below with the corresponding values of i and j.

i, j	N
1,0	01
1,1	03
2,0	04
2,1	07
3,1	13
3,2	19

Parameters

cell_radius (float) – Radius of the cells in the cluster.
num_cells (int) – Number of cells in the cluster.
pos (complex) – Central Position of the Cluster in the complex grid.
cluster_id (int) – ID of the cluster.
cell_type (str) – The type of the cell as a string. It can be either ‘simple’, ‘3sec’ or ‘square’. If it is ‘simple’ it means the standard hexagon shaped cell. If ‘3sec’ it means a 3 sectorized cell composed of 3 hexagons.
rotation (float) – Rotation of the cluster.

static _calc_cell_height(radius: float) → float [source]¶

Calculates the cell height from the cell radius.

Parameters: radius (float) – The cell Radius.
Returns: height – The cell height.
Return type: float

static _calc_cell_positions(cell_radius: float, num_cells: int, cell_type: str = 'simple', rotation: Optional[float] = None) → numpy.ndarray [source]¶

Helper function used by the Cluster class.

The calc_cell_positions method calculates the position (and rotation) of the ‘num_cells’ different cells, each with radius equal to ‘cell_radius’, so that they properly fit in the cluster.

Parameters

cell_radius (float) – Radius of each cell in the cluster.
num_cells (int) – Number of cells in the cluster.
cell_type (str) – The type of the cell. It should be a string with one of the possible values: ‘simple’, ‘3sec’, or ‘square’. If it is ‘simple’ it means the standard hexagon shaped cell. If ‘3sec’ it means a 3 sectorized cell composed of 3 hexagons.
rotation (float | None, optional) – Rotation of the cluster.

Returns

cell_positions – The first column of cell_positions has the positions of the cells in a cluster with num_cells cells with radius cell_radius. The second column has the rotation of each cell.

Return type

np.ndarray

static _calc_cell_positions_3sec(cell_radius: float, num_cells: int, rotation: Optional[float] = None) → numpy.ndarray [source]¶

Helper function used by the Cluster class.

The _calc_cell_positions_3sec method calculates the position (and rotation) of the ‘num_cells’ different cells, each with radius equal to ‘cell_radius’, so that they properly fit in the cluster.

Parameters

cell_radius (float) – Radius of each cell in the cluster.
num_cells (int) – Number of cells in the cluster.
rotation (float | None, optional) – Rotation of the cluster.

Returns

cell_positions – The first column of cell_positions has the positions of the cells in a cluster with num_cells cells with radius cell_radius. The second column has the rotation of each cell.

Return type

np.ndarray

static _calc_cell_positions_hexagon(cell_radius: float, num_cells: int, rotation: Optional[float] = None) → numpy.ndarray [source]¶

Helper function used by the Cluster class.

The calc_cell_positions method calculates the position (and rotation) of the ‘num_cells’ different cells, each with radius equal to ‘cell_radius’, so that they properly fit in the cluster.

Parameters

cell_radius (float) – Radius of each cell in the cluster.
num_cells (int) – Number of cells in the cluster.
rotation (float | None, optional) – Rotation of the cluster.

Returns

The first column of cell_positions has the positions of the cells in a cluster with num_cells cells with radius cell_radius. The second column has the rotation of each cell.

Return type

np.ndarray

static _calc_cell_positions_square(side_length: float, num_cells: int, rotation: Optional[float] = None) → numpy.ndarray [source]¶

Helper function used by the Cluster class.

The calc_cell_positions method calculates the position (and rotation) of the ‘num_cells’ different cells, each with side equal to ‘cell_radius’, so that they properly fit in the cluster.

Parameters

side_length (float) – The side length of each square cell in the cluster.
num_cells (int) – Number of cells in the cluster.
rotation (float | None, optional) – Rotation of the cluster.

Returns

cell_positions – The first column of cell_positions has the positions of the cells in a cluster with num_cells cells with radius cell_radius. The second column has the rotation of each cell.

Return type

np.ndarray

_calc_cluster_external_radius() → float [source]¶

Calculates the cluster external radius.

The cluster external radius is equal to the radius of the smallest circle (located at the center of the cluster) that contains the cluster. This circle should touch only the most external vertexes of the cells in the cluster.

Get the vertex positions of the last cell.

Returns: external_radius – The cluster external radius.
Return type: float

static _calc_cluster_radius(num_cells: int, cell_radius: float) → float [source]¶

Calculates the “cluster radius” for a cluster with “num_cells” cells, each cell with radius equal to “cell_radius”. The cluster “radius” is equivalent to half the distance between two clusters when they are in a Grid.

Parameters

num_cells (int) – Number of cells in the cluster.
cell_radius (float) – Radius of each cell in the cluster.

Returns

cluster_radius – The radius of a cluster with num_cells cells with radius cell_radius.

Return type

float

Notes

The cluster “radius” is equivalent to half the distance between two clusters.

static _get_ii_and_jj(num_cells: int) → Tuple[int, int][source]¶

Valid cluster sizes are given by the formula

\(N = i^2+i*j+j^2\)

where i and j are integer numbers and “N” is the number of cells in the cluster. This static function returns the values “i” and “j” for a given “N”. The values are summarized below.

i, j	N
1,0	01
1,1	03
2,0	04
2,1	07
3,1	13
3,2	19

Parameters: num_cells (int) – Number of cells in the cluster.
Returns: ii and jj – The ii and jj values corresponding to number of cells ‘num_cells’.
Return type: (int,int)

Notes

If num_cells is not in the table above then (0, 0) will be returned.

_get_outer_vertexes(vertexes: numpy.ndarray, central_pos: complex, distance: float) → numpy.ndarray [source]¶

Filter out vertexes closer to the shape center them distance.

This is a helper method used in the _get_vertex_positions method.

Parameters

vertexes (np.ndarray) – The outer vertexes of the cluster.
central_pos (complex) – Central position of the shape.
distance (float) – A minimum distance. Any vertex that is closer to the shape center then this distance will be removed.

Returns

outer_vertexes – The cluster outer vertexes.

Return type

np.ndarray

_get_vertex_positions() → numpy.ndarray [source]¶

Get the vertex positions of the cluster borders.

Returns: vertex_positions – The vertex positions of the cluster borders.
Return type: np.ndarray

Notes

This is only valid for cluster sizes from 1 to 19.

_ii_and_jj = {1: (1, 0), 3: (1, 1), 4: (2, 0), 7: (2, 1), 13: (3, 1), 19: (3, 2)}¶

_normalized_cell_positions: Dict[int, numpy.ndarray] = {}¶

add_border_users(cell_ids: Union[Iterable[int], int], angles: Union[Iterable[float], float], ratios: Union[Iterable[float], float] = 1.0, user_color: Optional[Union[str, Iterable[str]]] = None) → None [source]¶

Add users to all the cells indicated by cell_indexes at the specified angle(s) (in degrees) and ratio (relative distance from the center to the border of the cell).

Parameters

cell_ids (int | list[int] | np.ndarray) – IDs of the cells in the Cluster for which users will be added. The first cell has an ID equal to 1 and cell_ids may be an iterable with the IDs of several cells.
angles (float | list[float] | np.ndarray) – Angles (in degrees)
ratios (float | list[float]) – Ratios (from 0 to 1)
user_color (str | list[str]) – Color of the user’s marker.

Examples

>>> cluster = Cluster(cell_radius=1.0, num_cells=3)
>>> # Add a single user in the angle of 30 degrees with a ration of
>>> #  0.9 to the first cell in the cluster
>>> cluster.add_border_users(1, 30, 0.9)
>>>
>>> # Add 3 users at the angles of 0, 95 and 185 degrees to the
>>> # second cell of the cluster
>>> cluster.add_border_users(2, [0, 95, 185], 0.9, 'b')
>>>
>>> # Add one user in each cell at the angle of 10 degrees
>>> cluster.add_border_users([1, 2, 3], 10, 0.9, 'g')
>>>
>>> # Add a user in each cell at different angles per cell
>>> cluster.add_border_users([1, 2, 3], [90, 150, 190], 0.9, 'y')
>>>
>>> # Add multiple users to multiple cells at different angles
>>> cluster.add_border_users(                [1, 2, 3], [[180, 270], [-30], [60, 120]], 0.9, 'k')

add_random_users(cell_ids: Optional[Union[Iterable[int], int]] = None, num_users: Union[Iterable[int], int] = 1, user_color: Optional[Union[str, Iterable[str]]] = None, min_dist_ratio: Union[Iterable[float], float] = 0.0) → None [source]¶

Adds one or more users to the Cells with the specified cell IDs (the first cell has an ID equal to 1.).

Parameters

cell_ids (int | list[int] | np.ndarray) – IDs of the cells in the Cluster for which users will be added. The first cell has an ID equal to 1 and cell_ids may be an iterable with the IDs of several cells. If not provided, all cells will be assumed.
num_users (int | list[int] | np.ndarray) – Number of users to be added to each cell.
user_color (str | list[str], optional) – Color of the user’s marker.
min_dist_ratio (float, list[float], optional) – Minimum allowed (relative) distance between the cell center and the generated random user. See Cell.add_random_user method for details.

Notes

If cell_ids is an iterable then the other attributes (num_users, user_color and min_dist_ratio) may also be iterable with the same length of cell_ids in order to specifying individual values for each cell ID.

calc_dist_all_users_to_each_cell() → numpy.ndarray [source]¶

Returns a matrix with the distance from each user to each cell center.

This matrix is suitable to later calculate the path loss from each base station to each mobile station.

Because usually the base station is the transmitter and the mobile station is the receiver the matrix is such that each column corresponds to a different base station and each row corresponds to a different mobile station.

Returns: all_dists – Distance from each cell center to each user.
Return type: np.ndarray

Notes

There is no explicit indication from which cell each user came from. However, in a case, for instance, where there are 3 cells in the cluster with 2, 2 and 3 users in each of them, respectively, then the first 2 rows correspond to the users in the first cell, the following 2 rows correspond to the users in the second cell and the last three rows correspond to the users in the third cell.

calc_dist_all_users_to_each_cell_no_wrap_around() → numpy.ndarray [source]¶

Returns a matrix with the distance from each user to each cell center.

This matrix is suitable to later calculate the path loss from each base station to each mobile station.

Because usually the base station is the transmitter and the mobile station is the receiver the matrix is such that each column corresponds to a different base station and each row corresponds to a different mobile station.

Returns: all_dists – Distance from each cell center to each user.
Return type: np.ndarray

Notes

There is no explicit indication from which cell each user came from. However, in a case, for instance, where there are 3 cells in the cluster with 2, 2 and 3 users in each of them, respectively, then the first 2 rows correspond to the users in the first cell, the following 2 rows correspond to the users in the second cell and the last three rows correspond to the users in the third cell.

calc_dists_between_cells() → numpy.ndarray [source]¶

This method calculates the distance between any two cells in the cluster possibly considering wrap around.

If the create_wrap_around_cells method was called before this one, then when calculating the distance between two cells if the distance between a given cell and the wrapped version of another cell is smaller then the distance to that other cell it will be sued instead.

For instance, the

Returns: dists – A matrix with the distance from each cell to each other cell in the cluster.
Return type: np.ndarray

property cell_height¶

Get method for the cell_height property.

Returns: The height of the cells in the Cluster.
Return type: float

property cell_id_fontsize¶

Get method for the cell_id_fontsize property.

The value of cell_id_fontsize only matters for plotting the cluster.

Returns: The font size that should be used for the cell IDs in the plot.
Return type: int | None

property cell_radius¶

Get method for the cell_radius property.

Returns: The radius of the cells in the Cluster.
Return type: float

create_wrap_around_cells(include_users_bool: bool = False) → None [source]¶

This function will create the wrapped cells, as well as the wrap info data.

Parameters: include_users_bool (bool) – Set to True if the users of the original cells should appear in the wrapped version.

delete_all_users(cell_id: Optional[Union[Iterable[int], int]] = None) → None [source]¶

Remove all users from one or more cells.

If cell_id is an integer > 0, only the users from the cell whose index is cell_id will be removed. If cell_id is an iterable, then the users of cells pointed by it will be removed. If cell_id is None or not specified, then the users of all cells will be removed.

Parameters: cell_id (int | list[int], optional) – ID(s) of the cells from which users will be removed. If equal to None, all the users from all cells will be removed.

property external_radius¶

Get the external_radius of the Cluster.

Returns: The external_radius of the Cluster.
Return type: float

get_all_users() → List[pyphysim.cell.cell.Node][source]¶

Return all users in the cluster.

Returns: all_users – A list with all users in the cluster.
Return type: list[Node]

get_cell_by_id(cell_id: int) → pyphysim.cell.cell.CellBase [source]¶

Get the cell in the Cluster with the given cell_id.

Parameters: cell_id (int) – The ID of the desired cell.
Returns: c – The desired cell.
Return type: Cell

property num_cells¶

Get method for the num_cells property.

Returns: Number of cells in the Cluster.
Return type: int

property num_users¶

Get method for the num_users property.

Returns: The number of users in the Cluster.
Return type: int

plot(ax: Optional[Any] = None) → None [source]¶

Plot the cluster.

Parameters: ax (A matplotlib axis, optional) – The axis where the cluster will be plotted. If not provided, a new figure (and axis) will be created.

plot_border(ax: Optional[Any] = None) → None [source]¶

Plot only the border of the Cluster.

Only work’s for cluster sizes that can calculate the cluster vertices, such as cluster with 1, 7 or 19 cells.

Parameters: ax (A matplotlib axis, optional) – The axis where the cluster will be plotted. If not provided, a new figure (and axis) will be created.

property pos¶

Get the Cluster position.

Returns: The Cluster position.
Return type: complex

property radius¶

Get the radius of the Cluster object.

Returns: The radius of the Cluster object.
Return type: float

property rotation¶

Get method for the rotation property.

Returns: The shape rotation.
Return type: float

property vertices¶

Get the vertex positions of the cluster borders.

Returns: vertex_positions – The vertex positions of the cluster borders.
Return type: np.ndarray

Notes

This is only valid for cluster sizes from 1 to 19.

class pyphysim.cell.cell.Grid[source]¶

Bases: object

Class representing a grid of clusters of cells or a single cluster with its surrounding cells.

Valid cluster sizes are given by the formula \(N = i^2+i*j+j^2\) where i and j are integer numbers. The values allowed in the Cluster are summarized below with the corresponding values of i and j.

i, j	N
1,0	01
1,1	03
2,0	04
2,1	07
3,1	13
3,2	19

_calc_cluster_pos2() → complex [source]¶

Calculates the central position of clusters with 2 cells.

Returns: central_pos – Central position of the next cluster to be added to the Grid.
Return type: complex

Notes

The returned central position will depend on how many clusters were already added to the grid.

_calc_cluster_pos3() → complex [source]¶

Calculates the central position of clusters with 3 cells.

Returns: central_pos – Central position of the next cluster to be added to the Grid.
Return type: complex

Notes

The returned central position will depend on how many clusters were already added to the grid.

_calc_cluster_pos7() → complex [source]¶

Calculates the central position of clusters with 7 cells.

Returns: central_pos – Central position of the next cluster to be added to the Grid.
Return type: complex

Notes

The returned central position will depend on how many clusters were already added to the grid.

_colors = ['b', 'g', 'r', 'c', 'm', 'y', 'k', 'w']¶

_repr_png_() → Any[source]¶: Return the PNG representation of the shape.

_repr_some_format_(extension: str = 'png', axis_option: str = 'equal') → Any[source]¶

Return the representation of the shape in the desired format.

Parameters

extension (str) – The extension of the desired format. This should be something that the savefig method in a matplotlib figure can understand, such as ‘png’, ‘svg’, stc.
axis_option (str) – Option to be given to the ax.axis function.

Returns

The representation in the desired format.

Return type

Any

_repr_svg_() → Any[source]¶: Return the SVG representation of the shape.

clear() → None [source]¶: Clear everything in the grid.

create_clusters(num_clusters: int, num_cells: int, cell_radius: float) → None [source]¶

Create the clusters in the grid.

Parameters

num_clusters (int) – Number of clusters to be created in the grid.
num_cells (int) – Number of cells per clusters.
cell_radius (float) – The radius of each cell.

get_cluster_from_index(index: int) → pyphysim.cell.cell.Cluster [source]¶

Return the cluster object with index index in the Grid.

Parameters: index (int) – The index of the desirable cluster.
Returns: The desired cluster in the Grid.
Return type: Cluster

property num_clusters¶

Get method for the num_clusters property.

Returns: The number of clusters in teh grid.
Return type: int

plot(ax: Optional[Any] = None) → None [source]¶

Plot the grid of clusters.

Parameters: ax (A matplotlib axis, optional) – The axis where the grid will be plotted. If not provided, a new figure (and axis) will be created.

class pyphysim.cell.cell.Node(pos: complex, plot_marker: str = '*', marker_color: str = 'r', cell_id: Optional[Union[str, int]] = None, parent_pos: Optional[complex] = None)[source]¶

Bases: pyphysim.cell.shapes.Coordinate

Class representing a node in the network.

Parameters

pos (complex) – The position of the node in the complex grid.
plot_marker (str) – The marker to be used in a plot to represent the Node. This marker should be something that matplotlib can understand, such as ‘*’, for instance.
marker_color (str) – The color that will be used to plot the marker representing the Node. This color should be something that matplotlib can understand, such as ‘r’ for the color red, for instance.
cell_id (str, int, optional) – The ID of the cell where the Node is located.
parent_pos (complex) – The position of the cell where the Node is located (if any).

plot_node(ax: Optional[Any] = None) → None [source]¶

Plot the node using the matplotlib library.

If an axes ‘ax’ is specified, then the node is added to that axes. Otherwise a new figure and axes are created and the node is plotted to that.

Parameters: ax (A matplotlib axis, optional) – The axis where the node will be plotted. If not provided, a new figure (and axis) will be created.

property relative_pos¶

Get method for the relative_pos property.

Returns: The relative position of the Node regarding its parent Node’s position.
Return type: complex | None

pyphysim.cell.shapes module¶

Module implementing geometric shapes.

Each shape knows how to plot itself.

class pyphysim.cell.shapes.Circle(pos: complex, radius: float)[source]¶

Bases: pyphysim.cell.shapes.Shape

Circle shape class.

A circle is initialized only from a coordinate and a radius.

Parameters

pos (complex) – Coordinate of the center of the circle.
radius (float) – Circle’s radius.

_get_vertex_positions() → numpy.ndarray [source]¶

Calculates the vertex positions considering that the circle is at the origin (translation will be added automatically later).

Returns: vertex_positions – The positions of the vertexes of the shape.
Return type: np.ndarray

Notes

It does not make much sense to get the vertexes of a circle, since a circle ‘has’ infinite vertexes. However, for consistence with the Shape’s class interface the _get_vertex_positions is implemented such that it returns a subset of the circle vertexes. The number of returned vertexes was arbitrarily chosen as 12.

get_border_point(angle: float, ratio: Optional[float] = None) → complex [source]¶

Calculates the coordinate of the point that intercepts the border of the circle if we go from the origin with a given angle (in degrees).

Parameters

angle (float) – Angle in degrees
ratio (float) – The ratio from the cell center to the border where the desired point is located. It must be a value between 0 and 1.

Returns

point – A point in the line between the circle’s center and the circle’s border with the desired angle. If ratio is equal to one the point will be in the end of the line (touching the circle’s border)

Return type

complex

is_point_inside_shape(point: complex) → bool [source]¶

Test is a point is inside the circle

Parameters: point – A single complex number.
Returns: True if point is inside the circle, False otherwise.
Return type: inside_or_not

plot(ax: Any = None) → None [source]¶

Plot the circle using the Matplotlib library.

Parameters: ax (A matplotlib axis, optional) – The axis where the shape will be plotted. If not provided, a new figure (and axis) will be created.

Notes

If an axes ‘ax’ is specified, then the shape is added to that axes. Otherwise a new figure and axes are created and the shape is plotted to that.

class pyphysim.cell.shapes.Coordinate(pos: complex)[source]¶

Bases: object

Base class for a coordinate in a 2D grid.

A Coordinate object knows its location in the grid (represented as a complex number) and how to calculate the distance from it to another location.

calc_dist(other: pyphysim.cell.shapes.Coordinate) → float [source]¶

Calculates the distance to another coordinate.

Parameters: other (Coordinate) – A different coordinate object.
Returns: dist – Distance from self to the other coordinate.
Return type: float

move_by_relative_coordinate(rel_pos: complex) → None [source]¶

Move from the current position to the relative coordinate.

This is equivalent to moving to a new position given by the current position plus coordinate.

Parameters: rel_pos (complex) – Relative coordinate

move_by_relative_polar_coordinate(radius: float, angle: float) → None [source]¶

Move from the current position to the relative coordinate.

This is equivalent to moving to a new position given by the current position plus a the provided coordinate.

Parameters

radius (float) – Distance of the movement in the direction given by angle.
angle (float) – Angle (in radians) pointing the direction of the movement.

property pos¶

Get the coordinate position as a complex number.

Returns: The coordinate position (a complex number).
Return type: complex

class pyphysim.cell.shapes.Hexagon(pos: complex, radius: float, rotation: float = 0, **kw)[source]¶

Bases: pyphysim.cell.shapes.Shape

Hexagon shape class.

Besides the pos, radius and rotation properties from the Shape base class, the Hexagon also has a height property (read-only) from the base of the Hexagon to its center.

Parameters

pos (complex) – Coordinate of the shape in the complex grid.
radius (float) – Radius of the hexagon. It must be a positive number.
rotation (float) – Rotation of the hexagon in degrees.

_get_vertex_positions() → numpy.ndarray [source]¶

Calculates the vertex positions ignoring any rotation and considering that the hexagon is at the origin (rotation and translation will be added automatically later).

Returns: vertex_positions – The positions of the vertexes of the shape.
Return type: np.ndarray

property height¶

Get method for the height property.

Returns: The height of the Hexagon.
Return type: float

class pyphysim.cell.shapes.Rectangle(first: complex, second: complex, rotation: float = 0, **kw)[source]¶

Bases: pyphysim.cell.shapes.Shape

Rectangle shape class.

The rectangle is initialized from two coordinates as well as from the rotation.

Parameters

first (complex) – First coordinate (without rotation).
second (complex) – Second coordinate (without rotation).
rotation (float) – Rotation of the rectangle in degrees.

_get_vertex_positions() → numpy.ndarray [source]¶

Calculates the vertex positions ignoring any rotation and considering that the rectangle is at the origin (rotation and translation will be added automatically later).

Returns: vertex_positions – The positions of the vertexes of the shape.
Return type: np.ndarray

_repr_some_format_(extension: str = 'png', axis_option: str = 'tight') → Any[source]¶

Return the representation of the shape in the desired format.

Parameters

extension (str) – The extension of the desired format. This should be something that the savefig method in a matplotlib figure can understand, such as ‘png’, ‘svg’, stc.
axis_option (str) – Option to be given to the ax.axis function.

Notes

We only subclass the _repr_some_format_ method from the Shape class here so that we can change the axis_option to ‘tight’ (default in the Shape class is ‘equal’).

is_point_inside_shape(point: complex) → bool [source]¶

Test is a point is inside the rectangle

Parameters: point (complex) – A single complex number.
Returns: True if point is inside the rectangle, False otherwise.
Return type: bool

class pyphysim.cell.shapes.Shape(pos: complex, radius: float, rotation: float = 0, **kw)[source]¶

Bases: pyphysim.cell.shapes.Coordinate

Base class for all 2D shapes.

Each subclass must implement the _get_vertex_positions method.

Parameters

pos (complex) – Coordinate of the shape in the complex grid.
radius (float) – Radius of the shape. It must be positive.
rotation (float) – Rotation of the shape in degrees.

abstract _get_vertex_positions() → numpy.ndarray [source]¶

Calculates the vertex positions ignoring any rotation and considering that the shape is at the origin (rotation and translation will be added automatically later).

Returns: vertex_positions – The positions of the vertexes of the shape (as a 1D numpy array).
Return type: np.ndarray

Notes

Not implemented. Must be implemented in a subclass and return a one-dimensional numpy array (complex dtype) with the vertex positions.

_repr_png_() → Any[source]¶: Return the PNG representation of the shape.

_repr_some_format_(extension: str = 'png', axis_option: str = 'equal') → Any[source]¶

Return the representation of the shape in the desired format.

Parameters

extension (str) – The extension of the desired format. This should be something that the savefig method in a matplotlib figure can understand, such as ‘png’, ‘svg’, stc.
axis_option (str) – Option to be given to the ax.axis function.

Returns

Return type

output

_repr_svg_() → Any[source]¶: Return the SVG representation of the shape.

static calc_rotated_pos(cur_pos: ComplexOrArray, angle: float) → ComplexOrArray[source]¶

Rotate the complex numbers in the cur_pos array by angle (in degrees) around the origin.

Parameters

cur_pos (complex | np.ndarray) – The complex number(s) to be rotated.
angle (float) – Angle in degrees to rotate the positions.

Returns

rotated_pos – The rotate complex number(s).

Return type

complex | np.ndarray

get_border_point(angle: float, ratio: Optional[float] = None) → complex [source]¶

Calculates the coordinate of the point that intercepts the border of the shape if we go from the origin with a given angle (in degrees).

Parameters

angle (float) – Angle in degrees.
ratio (float) – The ratio from the cell center to the border where the desired point is located. This MUST be a value between 0 and 1.

Returns

point – A point in the line between the shape’s center and the shape’s border with the desired angle. If ratio is equal to one the point will be in the end of the line (touching the shape’s border)

Return type

complex

is_point_inside_shape(point: complex) → bool [source]¶

Test is a point is inside the shape.

Parameters: point – A single complex number.
Returns: True if point is inside the shape, False otherwise.
Return type: inside_or_not

plot(ax: Any = None) → None [source]¶

Plot the shape using the matplotlib library.

Parameters: ax (A matplotlib ax, optional) – The ax where the shape will be plotted. If not provided, a new figure (and ax) will be created.

Notes

If an axes ‘ax’ is specified, then the shape is added to that axes. Otherwise a new figure and axes are created and the shape is plotted to that.

property radius¶

Get method for the radius property.

Returns: The Shape radius.
Return type: float

property rotation¶

Get method for the rotation property.

Returns: The shape rotation.
Return type: float

property vertices¶

Get method for the vertices property.

Returns: The shape vertexes.
Return type: np.ndarray

property vertices_no_trans_no_rotation¶

Get the shape vertexes without translation and rotation.

Returns: vertex_positions – The positions of the vertexes of the shape without any translation or rotation (as a 1D numpy array).
Return type: np.ndarray

Module contents¶

Package with cell and shapes related modules.