Base¶

class antares.api.Base.Base(base=None, families=False)¶

Top-level container of Antares.

Main characteritics:

Indexed and insertion ordered dictionary.
- Return keys as a list and not KeysView nor dict_keys.
complex getitem operator including list, tuple, slice

Methods

`add_computer_function`(new_func)	Set a new function for the whole base.
`build_reduced_families`(base)	Build a copy of the families of a base with only subtrees and attrs.
`cell_to_node`([variables, report_boundaries])	Compute nodal values from cell-centered values.
`clear`()
`closest`(point[, coordinates, tolerance, ...])	Find the closest grid point mesh.
`compute`(var_name[, location, reset, store])	Compute a given variable on the whole base.
`compute_cell_normal`([coordinates, ...])	Compute the normal at the cell center of 2D elements in a 3D space.
`compute_cell_volume`([coordinates])	Compute the volume of the cells.
`compute_coordinate_system`([ttype, ...])	Compute a new coordinate system in the Base.
`copy`()
`create_local_families`()	Create a dict of all families with their local values in parallel.
`delete_variables`(list_vars[, location])	Delete variables in the base.
`deserialized`(pickable_base)	Build a base from its representation.
`dimension`([serial])	Dimension of the base.
`duplicate_variables`(list_vars, list_newvars)	Duplicate variables in the base.
`extract_families`(fam_names, d_local_families)	Extract a list of families out of a base.
`find_bounding_box`(var_name)	Get the bounding box of every zone based on the given variable.
`find_superblocks`([spblk_names])	Find blocks connected by joins.
`fromkeys`(iterable[, value])
`get`(k[,d])
`get_family`(family_name)	Return a family from its name.
`get_location`(location)	Return a new base.
`init`([zones, instants])	Initializing the structure of the Base object.
`is_structured`()	Tells if all Zones of a Base are structured or unstructured.
`items`()
`keys`()	Return keys as a list and not KeysView nor dict_keys.
`local_dimension`()	Dimension of the base on the current processor.
`minmax_var_from_family`(family_name, var_name)	Computes min and max values of the given variable in the family.
`node_to_cell`([variables])	Compute cell-centered values from nodal values.
`percent_to_absolute`(family_name, var_name, ...)	Computes the value between min and max values from the percentage.
`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`([conservative_vars, omega, angle])	Transform conservative variables.
`rename_variables`(list_vars, list_newvars[, ...])	Rename variables in the base.
`rename_zones`(zones, newzones)	Rename zones in the base.
`report_node_boundaries_values`([variables])	Report data from boundary to main location.
`serialized`([data])	Build a pickable representation of the base.
`set_computer_model`(modeling[, ...])	Set a computer modeling for the whole base.
`set_coordinate_names`()	Set the name of coordinate variables.
`set_families_to`(nbase)	Set the families to the base.
`set_formula`(formula)	Set a new formula for the whole base.
`set_formula_from_attrs`(name)	Set a new formula depending on zone attributes.
`setdefault`(k[,d])
`show`([all_inst])	Print a base in a fancy manner.
`squeeze`()	Squeeze.
`unstructure`()	Create an unstructured version of the Base.
`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
`update_reduced_families`(base)	Updates Family copies from a base to add reduced data.
`update_reduced_families_zone`(base, zone_key)	Updates Family copies from a base to add one reduced zone.
`values`()
`zone2keep`(cut_param)	Get only zones that include the value of the variable.

Attributes

`attrs`	Attribute (of type `AttrsManagement`) containing the attrs of the Base.
`coordinate_names`	Attribute (of type list(str)) containing the names of the spatial coordinates.
`families`	Attribute (of type `CustomDict`) containing the families of the Base.
`grid_points`	Return the number of nodes in the base.
`stats`	Compute statistics on the whole base.

add_computer_function(new_func)¶

Set a new function for the whole base.

The computer will receive a new function associated to its current modeling.

See Datasets.add_computer_function().

build_reduced_families(base)¶

Build a copy of the families of a base with only subtrees and attrs.

self stands for the reduced base. This operator is useful combined with update_reduced_families, to rebuild families after reduction treatments (e.g. cut).

See Family.build_reduced_copy for more details.

Parameters:: base (Base) – the “before reduction” base (self is the reduced one)

cell_to_node(variables=None, report_boundaries=False)¶

Compute nodal values from cell-centered values.

Variables located at cell centers will be processed to give new variables located at nodes.

Support boundary data - in this case, boundary values will be reported into the main part

Equivalent to:

atr = Treatment('cell2node')
atr['base'] = self
atr['variables'] = variables
atr['report_boundaries'] = report_boundaries
atr.execute()

Parameters:

variables (list(str) or None) – list of variables to process. if None, all variables are processed.
report_boundaries (bool) – toggle to enable data overwriting with boundary node data

closest(point, coordinates=['x', 'y', 'z'], tolerance=None, location='node')¶

Find the closest grid point mesh.

Find the closest grid point mesh to a given point in the Base and return its zone, indices and distance.

Parameters:

point (list(float)) – point coordinates (one value is associated to one variable defined in the parameter coordinates)
coordinates (list(str)) – list of variable names
tolerance (float) – as this method uses the method Instant.closest() on the first instant of each zone, if a tolerance is given, then it will check if the distance obtained on a zone is smaller than the tolerance. When this is true, the research will be stopped (consequently the tolerance is not used to find the closest point in a Instant)
location (str in LOCATIONS) – location of values of parameter coordinates

Returns:

the name of the zone in which the closest grid point mesh is located, the indices of that point and its distance to the given reference point

Return type:

a string, a tuple of integers, and a float

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

Compute a given variable on the whole base.

This variable is computed on all zones of the base.

Use the Zone.compute() method.

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_normal(coordinates=['x', 'y', 'z'], orientation=1, origin=None, unit=False)¶

Compute the normal at the cell center of 2D elements in a 3D space.

The three components of the normal vector are named with the following convention: (‘normal_<coordinate_name>’, ‘cell’).

Warning

works only on a 2D dataset: Geometric elements of 2D dimension in a 3D physical dimension (3 coordinates)

Parameters:

coordinates (list(3*str)) – List of coordinates.
orientation (int) – Sign of the normal orientation (1 is natural orientation defined by topology, -1 is the invert)
origin (list(float)) – Coordinates of the origin point used to set up the normal orientation (if it is not given the orientation is depending on the topology node ordering)
unit (bool) – if True then the output vectors are unit vectors

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 coordinates

compute_coordinate_system(ttype='cartesian2cylindrical', remove_current=False, current_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 Base.

Parameters:

ttype (str in ['cartesian2cylindrical', 'cylindrical2cartesian']) – type of transformation
remove_current (bool) – remove current coordinate system after transformation
current_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

‘ttype’=’cylindrical2cartesian’ is 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 the current ‘current_coord_sys’

create_local_families()¶

Create a dict of all families with their local values in parallel.

The dictionary keys are all family names. If the family exists on this process, the value is the family object. If the family does not exist on this process, the value is an empty family object.

It involves collective communications in parallel.

Returns:: the dictionary.
Return type:: dict

delete_variables(list_vars, location=None)¶

Delete variables in the base.

Parameters:

list_vars (list(str)) – list of variables to delete
location (str in LOCATIONS or ‘None’) – if None, delete the variables at the all locations

equivalent to del base[:, :, list_vars] which uses del with base slicing instead.

classmethod deserialized(pickable_base)¶: Build a base from its representation.

dimension(serial=False)¶

Dimension of the base.

Tells the dimension of the Base if all zones have the same dimension, otherwise it returns None.

Returns:: dimension of the Base
Return type:: int or None

duplicate_variables(list_vars, list_newvars, location=None)¶

Duplicate variables in the base.

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.

extract_families(fam_names, d_local_families)¶: Extract a list of families out of a base.

find_bounding_box(var_name)¶

Get the bounding box of every zone based on the given variable.

Only the first instant is considered.

Parameters:: var_name (string) – name of the variable used to compute the bounding box
Returns:: bounding box of every zone
Rtypes:: dictionary

find_superblocks(spblk_names={})¶

Find blocks connected by joins.

Find and set a family to the list of zones that are all connected by joins.

Returns:: list of superblocks names

get_family(family_name)¶

Return a family from its name.

In sequential, it is equivalent to: b.families[family_name]

In parallel, the family_name does not necessarily exist on each process. Hence, this method must be called collectively. If the family exists on any process but not on the current one, a void Family is returned.

Parameters:: family_name (str) – name of the family to extract.
Returns:: the family.
Return type:: Family

get_location(location)¶

Return a new base.

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

Parameters:: location (str in LOCATIONS) – location to extract
Returns:: the base with only specified location variables
Return type:: Base or None

init(zones=['0000'], instants=['0000'])¶

Initializing the structure of the Base object.

It creates all the zones and the instants based on the given list of zones and list of instants

Parameters:

zones – list of zones
instants – list of instants

is_structured()¶

Tells if all Zones of a Base are structured or unstructured.

If the Base contains both structured and unstructured Zones, then it returns None.

Returns:: the boolean telling if the Base is structured or not.
Return type:: bool or None

local_dimension()¶

Dimension of the base on the current processor.

Tells the dimension of the Base if all zones have the same dimension, otherwise it returns None.

Returns:: dimension of the Base
Return type:: int or None

minmax_var_from_family(family_name, var_name)¶

Computes min and max values of the given variable in the family.

Parameters:

family_name (str) – the family name
var_name (str) – the variable name on which the stats are computed

Returns:

min and max values

Rtypes:

floats

node_to_cell(variables=None)¶

Compute cell-centered values from nodal values.

Variables located at nodes will be processed to give new variables located at cell centers.

Support boundary data: account for nodal values from boundary conditions.

Function Instant.node_to_cell() is used.

Parameters:: variables (list(str) or None) – list of variables to process. if None, all variables are processed.

percent_to_absolute(family_name, var_name, percent)¶

Computes the value between min and max values from the percentage.

Computes the value between min and max values of the given variable in the family from the percentage.

Parameters:

family_name (str) – the family name
var_name (str) – the variable name
percent (float) – percentage

Returns:

min and max values

Rtypes:

floats

rel_to_abs(conservative_vars=['ro', 'rovx', 'rovy', 'rovz', 'roE'], omega='in_attr', angle='in_attr')¶

Transform conservative variables.

Transform conservative variables from relative frame to absolute frame by looping on all zones using the Zone.rel_to_abs() method.

Parameters:

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 base.

If the variables are the coordinates, then the coordinate names are changed accordingly.

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.

rename_zones(zones, newzones)¶

Rename zones in the base.

Replacement is performed element-wise.

Related to Family of type Zone.

Parameters:

zones (list(str)) – list of zones to rename
newzones (list(str)) – list of new zone names

report_node_boundaries_values(variables=None)¶

Report data from boundary to main location.

Apply only on nodal data

Parameters:: variables (list(str) or None) – list of variables to compute at cell, if None, compute all variables from node to cell

serialized(data=True)¶: Build a pickable representation of the base.

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

Set a computer modeling for the whole base.

See antares.api.Instant.Instant.set_computer_model().

set_coordinate_names()¶: Set the name of coordinate variables.

Warning

the coordinate names are recovered either from the shared variables of the first zone or from the variables of the first instant of the first zone. All zones must have the same coordinate names.

set_families_to(nbase)¶

Set the families to the base.

Parameters:: nbase (Base) – set families to this new base.

Warning

The base ‘nbase’ must be populated before using this method. The names of objects must be the same as the given base e.g.: in get_location and __get_tree_slice

set_formula(formula)¶

Set a new formula for the whole base.

The computer will receive a new formula associated to its current modeling.

See antares.api.Instant.Instant.set_formula()

set_formula_from_attrs(name)¶

Set a new formula depending on zone attributes.

The computer will receive a new formula associated to its current modeling. This formula is included in the zone attribute with the key name.

See Datasets.set_formula_from_attrs().

show(all_inst=0)¶

Print a base in a fancy manner.

Parameters:: all_inst (integer in [0, 1, 2, 3]) – tells the level of verbosity for instants

all_inst in binary notation: xy

y = 1: print all variable names from all instants
y = 0: print all variable names from the the first instant of the first zone

all_inst = 2: print all variable stats from all instants

squeeze()¶

Squeeze.

Remove single-dimensional entries from the shape of all the data array of the Base. Note that it is an in-place modification.

unstructure()¶

Create an unstructured version of the Base.

Equivalent to:

atr = Treatment('unstructure')
atr['base'] = base
atr.execute()

update_reduced_families(base)¶

Updates Family copies from a base to add reduced data.

self stands for the reduced base. This operator is useful combined with build_reduced_families, to rebuild families after reduction treatments (e.g. cut).

The zone names appearing in the reduced base (self) are added to the families, based on families of base. It means that each zone name in the reduced base must match one zone name in base. Only zones are added for the moment (it is not implemented for Boundary and Window)

See Family.update_reduced_copy for more details.

Parameters:: base (Base) – the “before reduction” base (self is the reduced one)

update_reduced_families_zone(base, zone_key)¶

Updates Family copies from a base to add one reduced zone.

The zone associated to zone_key is added to the families, based on families of base. It means that zone_key in the reduced base must match one zone name in base.

See Family.update_reduced_copy for more details.

Parameters:

base (Base) – the “before reduction” base (self is the reduced one)
zone_key (str) – the identifier of the zone to add in the families of the reduced base (self)

zone2keep(cut_param)¶

Get only zones that include the value of the variable.

Parameters:: cut_param (tuple (str, float)) – the variable name and the value
Returns:: list of zone names
Rtypes:: tuple of str

property attrs¶: Attribute (of type AttrsManagement) containing the attrs of the Base.

property coordinate_names¶: Attribute (of type list(str)) containing the names of the spatial coordinates.

property families¶: Attribute (of type CustomDict) containing the families of the Base.

property grid_points¶: Return the number of nodes in the base.

property stats¶

Compute statistics on the whole base.

A new base is returned with 5 zones named:

mean for the arithmetic mean,
var for the variance,
std for the standard deviation,
min,
max.

The arithmetic mean is the sum of the elements divided by the number of elements: \(\bar{y} = \frac{1}{n} \sum_{i=1}^{n} y_i\) . The variance is computed using the formula \(\sigma^2 = \frac{1}{n - 1}\sum_{i=1}^{n} (y_i - \bar{y})^2\). The standard deviation is the square root of the variance.

Returns:: the base containing the statistics
Return type:: Base