Instant

Container of numpy arrays.

An instant object is a collection of numpy arrays.

It contains several variables that can be located at the center of the geometrical element (cell), at the node, at the interfaces, or at a mix of cells and interfaces: cellfict.

From Python 3.7, python dictionaries store key-value pairs in the order they were inserted. They are insertion ordered.

The parent class UserDict acts as a wrapper around dictionary objects. This class can be easier to work with because the underlying dictionary is accessible as an attribute.

The alternative would be to use a MutableMapping that defines the interface, but we would need to store the data explicitely.

class antares.api.Instant.Instant(instant=None, connectivity=False, inherit_computer=None)

Indexed and insertion ordered dictionary of numpy arrays.

Contains several variables that can be located at the center of the cells or at the node.

Keys are of the form: (‘name of variables’, location).

Return keys as a list and not KeysView nor dict_keys.

Methods

add_computer_function(new_func)

Setter of the function.

are_all_shared(variables)

Check if variables are all shared.

cell_shape()

Get the cell shape of the instant.

clear()

closest(value, variables)

Get the closest indices to the values for the given variables.

compute(var_name[, location, reset, store])

Compute a given variable for the instant.

compute_cell_volume([coordinates])

Compute the volume of the cells.

compute_coordinate_system([ttype, ...])

Compute a new coordinate system in the instant.

copy()

delete_variables(list_vars[, location])

Delete variables in the instant.

deserialized(pickable_instant)

Build an instant from its representation.

dimension()

Return the dimension.

duplicate_variables(list_vars, list_newvars)

Duplicate variables in the instant.

fromkeys(iterable[, value])

get(k[,d])

get_celltype(celltype)

Return the subset of the instant with only a given element type.

get_location(location)

Return a copy of the Instant containing only the variables located in the original Instant at the specified location.

is_structured()

Tell whether the instant is structured or not.

is_unstructured()

Tells whether the instant is unstructured or not.

items()

keys([location, with_shared])

Get the list of all variable names.

mesh_orientation(coordinate_names)

Give the orientation of a 3D structured mesh.

node_to_cell([variables, with_shared])

Compute variables at cell centers from values given at nodes.

pop(k[,d])

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem()

as a 2-tuple; but raise KeyError if D is empty.

rel_to_abs([coordinates, conservative_vars, ...])

Transform conservative variables in the instant from relative frame to absolute frame.

rename_variables(list_vars, list_newvars[, ...])

Rename variables in the instant.

serialized([data])

Build a pickable representation of the instant.

set_computer_model(modeling[, ...])

Setter of the computer.

set_formula(formula)

Setter of the formula.

setdefault(k[,d])

update([E, ]**F)

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values()

Attributes

attrs

Get the attributes of the Instant.

computer

Get the computer.

connectivity

Get the connectivities for unstructured grid.

shape

Get the shape of the Instant.

add_computer_function(new_func)

Setter of the function.

Parameters

new_func (func) – a python function.

are_all_shared(variables)

Check if variables are all shared.

Parameters

variables (list(str), or list(tuple(str)) e.g.: ['x', 'y'] or [('x','node'), ('y','cell')]) – Variable names.

Returns

says if all the variables passed as parameters are shared

Return type

bool

cell_shape()

Get the cell shape of the instant.

Returns

the shape of the cell-centered variables

Return type

int or ndarray(int)

closest(value, variables)

Get the closest indices to the values for the given variables.

Parameters
  • value (list of floats) – values to be close to

  • variables (list(str)) – variables scanned

Returns

index and distance of the closest point

Return type

(tuple of integer, real)

compute(var_name, location=None, reset=False, store=True)

Compute a given variable for the instant.

This variable is computed with variables available in the instant.

Parameters
  • var_name (str) – The name of the variable to compute.

  • location (str in LOCATIONS) – The location of the variable. If None, the default location is assumed.

  • reset (bool) – Remove temporary fields stored in the equation manager.

  • store (bool) – Store temporary fields in the equation manager.

compute_cell_volume(coordinates=['x', 'y', 'z'])

Compute the volume of the cells.

It is stored with the variable name (‘cell_volume’, ‘cell’).

Parameters

coordinates (list(str)) – list of coordinate names

compute_coordinate_system(ttype='cartesian2cylindrical', remove_actual=False, actual_coord_sys=['x', 'y', 'z'], new_coord_sys=['x', 'r', 'theta'], origin=[0.0, 0.0, 0.0])

Compute a new coordinate system in the instant.

name DEFAULT_CARTESIAN_COORDINATES name DEFAULT_CYLINDRICAL_COORDINATES

Parameters
  • ttype (str in ['cartesian2cylindrical', 'cylindrical2cartesian']) – type of transformation

  • remove_actual (bool) – remove actual coordinate system after transformation

  • actual_coord_sys (list of 3 str) – names of the current coordinates

  • new_coord_sys (list of 3 str) – names of the new coordinates

  • origin (list of 3 float) – position of the origin

Warning

‘cylindrical2cartesian’ with non zero origin not implemented

for ‘ttype’=’cartesian2cylindrical’, in ‘new_coord_sys’, the first coordinate is the axial direction, the second the radial one, and the third the azimuthal one (by default (x, r, \(\theta\)))

The first coordinate name in ‘new_coord_sys’ must also be into ‘actual_coord_sys’.

delete_variables(list_vars, location=None)

Delete variables in the instant.

Parameters
  • list_vars (list(str)) – list of variables to delete

  • location (str in LOCATIONS or ‘None’) – if None, delete the variables at all locations

classmethod deserialized(pickable_instant)

Build an instant from its representation.

dimension()

Return the dimension.

Returns

dimension of the Instant

Return type

int

duplicate_variables(list_vars, list_newvars, location=None)

Duplicate variables in the instant.

Parameters
  • list_vars (list(str)) – list of variables to duplicate

  • list_newvars (list(str)) – list of new variable names

  • location (str in LOCATIONS) – if different from None, change only the variables at the location specified

Duplication is performed element-wise.

get(k[, d]) D[k] if k in D, else d.  d defaults to None.
get_celltype(celltype)

Return the subset of the instant with only a given element type.

Parameters

celltype (str) – type of cells in [‘tet’, ‘pyr’, ‘hex’, ‘pri’, ‘tri’, ‘qua’]

Returns

a copy of the instant with only element of the given type

get_location(location)

Return a copy of the Instant containing only the variables located in the original Instant at the specified location.

Variables (numpy arrays) are NOT deep copied. They are references to the original variables.

Parameters

location (string in LOCATIONS) – location to extract

Returns

the Instant with only specified location variables

Return type

Instant or None

is_structured()

Tell whether the instant is structured or not.

Returns

the boolean telling if the Instant is structured or not.

Return type

bool

is_unstructured()

Tells whether the instant is unstructured or not.

Returns

the boolean telling if the Instant is unstructured or not.

Return type

bool

keys(location=None, with_shared=True)

Get the list of all variable names.

Force the return type to a list and not KeysView nor dict_keys.

Parameters
  • location (string in LOCATIONS) – if different from None, lists only the variables at the location specified

  • with_shared (bool) – if True, it will include the variables contained in the shared Instant

Returns

the Instant variables

Return type

list(str) when location is set list(tuple(str, str)) when location is None

mesh_orientation(coordinate_names)

Give the orientation of a 3D structured mesh.

A 3D structured mesh has orientation 1 if at each node, (i, j, k) directions form a right-handed oriented basis. Otherwise, it has a -1 orientation.

The coordinates must be at node.

Parameters

coordinate_names (list(str)) – the name of variables defining the coordinates

Returns

1 if right-handed oriented, -1 if left-handed oriented, 0 if undefined

Return type

int

node_to_cell(variables=None, with_shared=True)

Compute variables at cell centers from values given at nodes.

The parent object is not involved in the process, i.e. the variables contained in a potential associated shared instant are omitted.

Parameters
  • variables (list(str) or None) – list of variables to compute at cell. If None, operate on all variables contained in the object. If a given variable does not exist, it is silently omitted.

  • with_shared (bool) – tell if shared variables should be considered. By default, shared variables will be processed.

rel_to_abs(coordinates=['x', 'y', 'z'], conservative_vars=['ro', 'rovx', 'rovy', 'rovz', 'roE'], omega='in_attr', angle='in_attr')

Transform conservative variables in the instant from relative frame to absolute frame.

Parameters
  • coordinates (list(str)) – List of coordinate names.

  • conservative_vars (list(str)) – List of conservative variables names in the following order: density, momentum along the x-axis; momentum along the y-axis, momentum along the z-axis and total energy per unit of volume

  • omega (float) – Angular speed of the current base. If in_attr use the omega stored in the attrs, necessary if different angular speeds in the base (for example one angular speed per superblock)

  • angle (float) – Angular deviation of the current base. If in_attr use the angle stored in the attrs, necessary if different angular deviations in the base (for example one angular deviation per superblock and per instant)

Note

may be moved elsewhere in future releases

Warning

the angular speed must be perpendicular to the x-axis

rename_variables(list_vars, list_newvars, location=None)

Rename variables in the instant.

Parameters
  • list_vars (list(str)) – list of variables to rename

  • list_newvars (list(str)) – list of new variable names

  • location (str in LOCATIONS) – if different from None, change only the variables at the location specified

Replacement is performed element-wise.

serialized(data=True)

Build a pickable representation of the instant.

set_computer_model(modeling, species_database=None, addons=None)

Setter of the computer.

Parameters
  • modeling (str) – The name of a set of equations. This modeling contains equations (python functions). They can be found in the directory named as the modeling in the directory named formula. ex: the modeling directory internal must be in the directory formula.

  • species_database (str) – The filename that contains the information about chemical species in some specific modelings.

  • addons (list(str)) – List of additional files (without the python extension) that are located in the directory <modeling_name/formula/addons>.

set_formula(formula)

Setter of the formula.

Parameters

formula (str) – The name of the new formula.

property attrs

Get the attributes of the Instant.

Return type

antares.core.AttrsManagement.AttrsManagement

property computer

Get the computer.

property connectivity

Get the connectivities for unstructured grid.

See the section Connectivity for more information.

Returns

the connectivities for unstructured grid

Return type

antares.core.CustomDict.CustomDict

property shape

Get the shape of the Instant.

The shape is considered to be the shape of numpy arrays of the node variables contained in the Instant.

Returns

the shape

Return type

tuple(int)


Connectivity

The connectivity object is an Instant attribute of type CustomDict. It is used to store the connectivity arrays of unstructured grids. An unstructured grid is a collection of points that form geometrical elements (2D or 3D). A mesh element can be described in many ways with its vertices, edges, or faces.

In a vertex-based description, a mesh element is defined with vertices. Antares handle standard (or canonical) linear mesh elements: segment, triangle, quadrilateral, tetrahedron, hexahedron, prism, and pyramid. High-order (quadratic, cubic) mesh elements are not considered. The number of vertices per element (or nodes per cell) for each element type is given by:

Constants.NODES_PER_CELL = {'bi': 2, 'hex': 8, 'pri': 6, 'pyr': 5, 'qua': 4, 'tet': 4, 'tri': 3}

The grid connectivity of each element type is stored in the connectivity attribute:

Instant.connectivity['tri'] = tri_table
Instant.connectivity['qua'] = qua_table

The connectivity table is a two-dimensional numpy array of shape (number of cells of this element type, number of nodes per cell for this element type). The order in which the nodes of a cell are listed is important, and is described in the following picture for the various cell types.

../../_images/connectivity_elements.png

In a face-based description, a mesh element is defined with faces, and the faces are defined with vertices. This enables to tackle with polygons (‘pgon’) and polyhedras (‘phed’).

The grid connectivity of polygons and polyhedras is stored in the connectivity attribute:

poly_conn = PolygonCells()
instant.connectivity['pgon'] = poly_conn

polyhedra = PolyhedronBCells()
instant.connectivity['phed'] = polyhedra

This time, the connectivity is an object of type PolygonCells or PolyhedronBCells.

PolygonCells

Class to store and manipulate polygonal cells.

The polygonal cells are represented as two 1D arrays. The first one stores multiple sorted lists of vertex ids that form each polygon. Care must be taken on the order of the vertices since it determines the orientation of the polygon in the space (see Cells2D documentation). The second one stores the starting index (called “offset”) of each list to enable constant-time random access in the data-structure.

class antares.api.connectivity.PolygonCells.PolygonCells
add_vertices_of_cell(vertex_ids)

Add one cell specified by its sorted vertices.

Parameters

vertex_ids (list or np.array) – list of ids of vertices representing the cell.

get_number_of_cells()

Give the total number of cells stored in the data-structure.

Returns

the total number of cells stored in the data-structure.

Return type

int

get_number_of_vertices()

Alternative len(set(self._c2v)) is slower.

get_vertices_of_cell(cell_idx)

Provide vertex ids of one cell.

Parameters

cell_idx (int) – the cell from which extract the vertices.

Returns

the vertex ids as a 1D array.

Return type

indexable

get_vertices_of_cells(with_offsets=False)

Provide vertex ids of all cells.

The vertex ids are given as a 1D array. If with_offsets flag is set, a list of offsets allowing to do random access on cell array is returned.

Parameters

with_offsets (bool) – returns list of offsets to identify each cell’s list of faces.

Returns

an array of vertex ids or a tuple (array of face ids, offsets) if with_offsets flag is set.

Return type

indexable or tuple

set_vertices_of_cells(c2v, c2v_offsets)

Reset cells to vertices connectivity.

Parameters
  • c2v (np.array) – concatenation of the list of vertices of each cell stored as a 1D array).

  • c2v_offsets – list of starting indices of each cell plus the number of data in c2v (stored as a 1D array).

PolyhedronBCells

Class to store and manipulate polyhedral cells with representation (B).

Representation (B) stores the oriented faces forming each polyhedral cell and the vertices forming each polygonal face.

The lists of oriented faces of cells are represented as two 1D arrays. The first one stores multiple sorted lists of face ids that form each cell using the convention for face indices (see Cells3D documentation). Care must be taken on the orientation of faces (see Cells3D documentation). The second one stores the starting index (called “offset”) of each list to enable constant-time random access in the data-structure.

The polygonal faces are represented as two 1D arrays. The first one stores multiple sorted lists of vertex ids that form each polygon. Care must be taken on the order of the vertices since it determines the orientation of the polygon in the space (see Cells3D documentation). The second one stores the starting index (called “offset”) of each list to enable constant-time random access in the data-structure.

class antares.api.connectivity.PolyhedronBCells.PolyhedronBCells
add_faces_of_cell(face_ids)

Add one cell specified by its faces.

Parameters

face_ids (list or np.array) – list of ids of faces representing the cell.

add_vertices_of_face(vertex_ids)

Add one face specified by its sorted vertices.

Parameters

vertex_ids (list or np.array) – list of ids of vertices representing the face.

get_faces_of_cell(cell_idx)

Provide face ids of one cell.

Parameters

cell_idx (int.) – the cell from which extract the faces.

Returns

the face ids as a 1D array.

Return type

indexable

get_faces_of_cells(with_offsets=False)

Provide face ids of all cells.

The face ids are given as a 1D array. If with_offsets flag is set, a list of offsets allowing to do random access on cell array is returned.

Parameters

with_offsets (bool) – returns list of offsets to identify each cell’s list of faces.

Returns

an array of vertex ids or a tuple (array of face ids, offsets) if with_offsets flag is set.

Return type

indexable or tuple

get_number_of_cells()

Give the total number of cells stored in the data-structure.

Returns

the total number of cells stored in the data-structure.

Return type

int

get_number_of_faces()

Give the total number of faces stored in the data-structure.

One face is counted for two faces having only a different orientation.

Returns

the total number of faces stored in the data-structure.

Return type

int

get_number_of_vertices()

Alternative len(set(self._f2v)) is slower.

get_vertices_of_cell(cell_idx)

Provide vertex ids of one cell.

Parameters

cell_idx (int.) – the cell from which extract the vertices.

Returns

the vertex ids as a 1D array.

Return type

indexable

get_vertices_of_cells(with_offsets=False)

Provide vertex ids of all cells.

The vertex ids are given as a 1D array. If with_offsets flag is set, a list of offsets allowing to do random access on cell array is returned.

Parameters

with_offsets (bool) – returns list of offsets to identify each cell’s list of faces.

Returns

an array of vertex ids or a tuple (array of face ids, offsets) if with_offsets flag is set.

Return type

indexable or tuple

get_vertices_of_face(face_idx)

Provide vertex ids of one face.

Parameters

face_idx (int) – the face from which extract the vertices. If goes from 1 to N_faces or from -1 to N_faces.

Returns

the vertex ids as a 1D array.

Return type

indexable

get_vertices_of_faces(with_offsets=False)

Provide vertex ids of all faces.

The vertex ids are given as a 1D array. Only one orientation of each face is stored in this array. If with_offsets flag is set, a list of offsets allowing to do random access on face array is returned.

Parameters

with_offsets (bool) – returns list of offsets to identify each face’s list of vertices.

Returns

an array of vertex ids or a tuple (array of face ids, offsets) if with_offsets flag is set.

Return type

indexable or tuple

set_faces_of_cells(c2f, c2f_offsets)

Reset cells to faces connectivity.

Parameters
  • c2f (np.array) – concatenation of the list of faces of each cell stored as a 1D array).

  • c2f_offsets (np.array) – list of starting indices of each cell plus the number of data in c2f (stored as a 1D array).

set_vertices_of_faces(f2v, f2v_offsets)

Reset faces to vertices connectivity.

Parameters
  • f2v (np.array) – concatenation of the list of vertices of each face stored as a 1D array).

  • f2v_offsets (np.array) – list of starting indices of each face plus the number of data in f2v (stored as a 1D array).