plaid.containers.features ========================= .. py:module:: plaid.containers.features .. autoapi-nested-parse:: Module for implementing collections of features within a Sample. Classes ------- .. autoapisummary:: plaid.containers.features.SampleFeatures Module Contents --------------- .. py:class:: SampleFeatures(data: Optional[dict[float, plaid.types.CGNSTree]] = None) A container for meshes within a Sample. :param data: A dictionary mapping time steps to CGNSTrees. Defaults to None. :type data: dict[float, CGNSTree], optional .. py:attribute:: data :type: dict[float, plaid.types.CGNSTree] .. py:attribute:: defaults .. py:method:: set_default_time(time: float) -> None Set the default active time. Calls the DefaultManager to set the default time. :param time: The time to set as the default active time. :type time: float .. py:method:: set_default_base(base_name: str, time: Optional[float] = None) -> None Set the default active base. Calls the DefaultManager to set the default base. :param base_name: The base name to set as the default active base. :type base_name: str :param time: The time at which to set the default base. Defaults to None. :type time: float, optional .. py:method:: set_default_zone_base(zone_name: str, base_name: str, time: Optional[float] = None) -> None Set the default active zone within a base. Calls the DefaultManager to set the default zone and base. :param zone_name: The zone name to set as the default active zone. :type zone_name: str :param base_name: The base name in which the zone is located. :type base_name: str :param time: The time at which to set the default zone and base. Defaults to None. :type time: float, optional .. py:method:: resolve_time(time: Optional[float] = None) -> float Get the resolved time assignment. Calls the DefaultManager to resolve the time. :param time: The time to resolve. Defaults to None. :type time: float, optional :returns: The resolved time. :rtype: float .. py:method:: resolve_base(base_name: Optional[str] = None, time: Optional[float] = None) -> Optional[str] Get the resolved base assignment. Calls the DefaultManager to resolve the base. :param base_name: The base name to resolve. Defaults to None. :type base_name: str, optional :param time: The time at which to resolve the base. Defaults to None. :type time: float, optional :returns: The resolved base name. :rtype: Optional[str] .. py:method:: resolve_zone(zone_name: Optional[str] = None, base_name: Optional[str] = None, time: Optional[float] = None) -> Optional[str] Get the resolved zone assignment. Calls the DefaultManager to resolve the zone. :param zone_name: The zone name to resolve. Defaults to None. :type zone_name: str, optional :param base_name: The base name in which the zone is located. Defaults to None. :type base_name: str, optional :param time: The time at which to resolve the zone. Defaults to None. :type time: float, optional :returns: The resolved zone name. :rtype: Optional[str] .. py:method:: get_all_time_values() -> list[float] Retrieve all time steps corresponding to the meshes, if available. :returns: A list of all available time steps. :rtype: list[float] .. py:method:: get_all_mesh_times() -> list[float] DEPRECATED: Use :meth:`get_all_time_values` instead. .. py:method:: init_tree(time: Optional[float] = None) -> plaid.types.CGNSTree Initialize a CGNS tree structure at a specified time step or create a new one if it doesn't exist. :param time: The time step for which to initialize the CGNS tree structure. If a specific time is not provided, the method will display the tree structure for the default time step. :type time: float, optional :returns: The initialized or existing CGNS tree structure for the specified time step. :rtype: CGNSTree (list) .. py:method:: get_tree(time: Optional[float] = None, only_mesh: bool = False) -> Optional[plaid.types.CGNSTree] Retrieve the CGNS tree structure for a specified time step, if available. :param time: The time step for which to retrieve the CGNS tree structure. If a specific time is not provided, the method will display the tree structure for the default time step. :type time: float, optional :param only_mesh: If True, features of type global and fields are removed from the sample :type only_mesh: bool :returns: The CGNS tree structure for the specified time step if available; otherwise, returns None. :rtype: CGNSTree .. py:method:: set_trees(meshes: dict[float, plaid.types.CGNSTree]) -> None Set all meshes with their corresponding time step. :param meshes: Collection of time step with its corresponding CGNSTree. :type meshes: dict[float,CGNSTree] :raises KeyError: If there is already a CGNS tree set. .. py:method:: add_tree(tree: plaid.types.CGNSTree, time: Optional[float] = None, in_place: bool = True) -> plaid.types.CGNSTree Merge a CGNS tree into the tree stored at a given time. If there is no tree at ``time``, ``tree`` is stored directly. Otherwise, Base nodes from ``tree`` are appended only when their name does not already exist in the destination tree. Bases with duplicate names are ignored and a warning is emitted. :param tree: CGNS tree to add. :type tree: CGNSTree :param time: Time step at which the tree is added. If omitted, the default time resolution is used. :type time: float, optional :param in_place: Controls ownership of the input tree. When ``True`` (default), the provided object may be stored/used directly. When ``False``, the input tree is deep-copied before insertion. :type in_place: bool, optional :raises ValueError: If ``tree`` is an empty list. :returns: The resulting tree for the resolved ``time``. :rtype: CGNSTree .. py:method:: del_tree(time: float) -> plaid.types.CGNSTree Delete the CGNS tree for a specific time. :param time: The time step for which to delete the CGNS tree structure. :type time: float :raises KeyError: There is no CGNS tree in this Sample / There is no CGNS tree for the provided time. :returns: The deleted CGNS tree. :rtype: CGNSTree .. py:method:: get_topological_dim(base_name: Optional[str] = None, time: Optional[float] = None) -> int Get the topological dimension of a base node at a specific time. :param base_name: The name of the base node for which to retrieve the topological dimension. Defaults to None. :type base_name: str, optional :param time: The time at which to retrieve the topological dimension. Defaults to None. :type time: float, optional :raises ValueError: If there is no base node with the specified `base_name` at the given `time` in this sample. :returns: The topological dimension of the specified base node at the given time. :rtype: int .. py:method:: get_physical_dim(base_name: Optional[str] = None, time: Optional[float] = None) -> int Get the physical dimension of a base node at a specific time. :param base_name: The name of the base node for which to retrieve the topological dimension. Defaults to None. :type base_name: str, optional :param time: The time at which to retrieve the topological dimension. Defaults to None. :type time: float, optional :raises ValueError: If there is no base node with the specified `base_name` at the given `time` in this sample. :returns: The topological dimension of the specified base node at the given time. :rtype: int .. py:method:: init_base(topological_dim: int, physical_dim: int, base_name: Optional[str] = None, time: Optional[float] = None) -> plaid.types.CGNSNode Create a Base node named `base_name` if it doesn't already exists. :param topological_dim: Cell dimension, see [CGNS standard](https://pycgns.github.io/PAT/lib.html#CGNS.PAT.cgnslib.newCGNSBase). :type topological_dim: int :param physical_dim: Ambient space dimension, see [CGNS standard](https://pycgns.github.io/PAT/lib.html#CGNS.PAT.cgnslib.newCGNSBase). :type physical_dim: int :param base_name: If not specified, uses `mesh_base_name` specified in Sample initialization. Defaults to None. :type base_name: str :param time: The time at which to initialize the base. If a specific time is not provided, the method will display the tree structure for the default time step. :type time: float, optional :returns: The created Base node. :rtype: CGNSNode .. py:method:: del_base(base_name: str, time: float) -> plaid.types.CGNSTree Delete a CGNS base node for a specific time. :param base_name: The name of the base node to be deleted. :type base_name: str :param time: The time step for which to delete the CGNS base node. :type time: float :raises KeyError: There is no CGNS tree in this sample / There is no CGNS tree for the provided time. :raises KeyError: If there is no base node with the given base name or time. :returns: The tree at the provided time (without the deleted node) :rtype: CGNSTree .. py:method:: get_base_names(full_path: bool = False, unique: bool = False, time: Optional[float] = None) -> list[str] Return Base names. :param full_path: If True, returns full paths instead of only Base names. Defaults to False. :type full_path: bool, optional :param unique: If True, returns unique names instead of potentially duplicated names. Defaults to False. :type unique: bool, optional :param time: The time at which to check for the Base. If a specific time is not provided, the method will display the tree structure for the default time step. :type time: float, optional :rtype: list[str] .. py:method:: has_base(base_name: str, time: Optional[float] = None) -> bool Check if a CGNS tree contains a Base with a given name at a specified time. :param base_name: The name of the Base to check for in the CGNS tree. :type base_name: str :param time: The time at which to check for the Base. If a specific time is not provided, the method will display the tree structure for the default time step. :type time: float, optional :returns: `True` if the CGNS tree has a Base called `base_name`, else return `False`. :rtype: bool .. py:method:: has_globals(time: Optional[float] = None) -> bool Check if a CGNS tree contains globals a given name at a specified time. :param time: The time at which to check for the Base. If a specific time is not provided, the method will display the tree structure for the default time step. :type time: float, optional :returns: `True` if the CGNS tree has a Base called `Globals`, else return `False`. :rtype: bool .. py:method:: get_base(base_name: Optional[str] = None, time: Optional[float] = None) -> plaid.types.CGNSNode Return Base node named `base_name`. If `base_name` is not specified, checks that there is **at most** one base, else raises an error. :param base_name: The name of the Base node to retrieve. Defaults to None. Defaults to None. :type base_name: str, optional :param time: Time at which you want to retrieve the Base node. If a specific time is not provided, the method will display the tree structure for the default time step. :type time: float, optional :returns: The Base node with the specified name or None if it is not found. :rtype: CGNSNode or None .. py:method:: init_zone(zone_shape: plaid.types.Array, zone_type: str = CGK.Unstructured_s, zone_name: Optional[str] = None, base_name: Optional[str] = None, time: Optional[float] = None) -> plaid.types.CGNSNode Initialize a new zone within a CGNS base. :param zone_shape: An array specifying the shape or dimensions of the zone. :type zone_shape: Array :param zone_type: The type of the zone. Defaults to CGK.Unstructured_s. :type zone_type: str, optional :param zone_name: The name of the zone to initialize. If not provided, uses `mesh_zone_name` specified in Sample initialization. Defaults to None. :type zone_name: str, optional :param base_name: The name of the base to which the zone will be added. If not provided, the zone will be added to the currently active base. Defaults to None. :type base_name: str, optional :param time: The time at which to initialize the zone. If a specific time is not provided, the method will display the tree structure for the default time step. :type time: float, optional :raises KeyError: If the specified base does not exist. You can create a base using `Sample.init_base(base_name)`. :returns: The newly initialized zone node within the CGNS tree. :rtype: CGLNode .. py:method:: del_zone(zone_name: str, base_name: str, time: float) -> plaid.types.CGNSTree Delete a zone within a CGNS base. :param zone_name: The name of the zone to be deleted. :type zone_name: str :param base_name: The name of the base from which the zone will be deleted. If not provided, the zone will be deleted from the currently active base. Defaults to None. :type base_name: str, optional :param time: The time step for which to delete the zone. Defaults to None. :type time: float, optional :raises KeyError: There is no CGNS tree in this sample / There is no CGNS tree for the provided time. :raises KeyError: If there is no base node with the given base name or time. :returns: The tree at the provided time (without the deleted node) :rtype: CGNSTree .. py:method:: get_zone_names(base_name: Optional[str] = None, full_path: bool = False, unique: bool = False, time: Optional[float] = None) -> list[str] Return list of Zone names in Base named `base_name` with specific time. :param base_name: Name of Base where to search Zones. If not specified, checks if there is at most one Base. Defaults to None. :type base_name: str, optional :param full_path: If True, returns full paths instead of only Zone names. Defaults to False. :type full_path: bool, optional :param unique: If True, returns unique names instead of potentially duplicated names. Defaults to False. :type unique: bool, optional :param time: The time at which to check for the Zone. If a specific time is not provided, the method will display the tree structure for the default time step. :type time: float, optional :returns: List of Zone names in Base named `base_name`, empty if there is none or if the Base doesn't exist. :rtype: list[str] .. py:method:: has_zone(zone_name: str, base_name: Optional[str] = None, time: Optional[float] = None) -> bool Check if the CGNS tree contains a Zone with the specified name within a specific Base and time. :param zone_name: The name of the Zone to check for. :type zone_name: str :param base_name: The name of the Base where the Zone should be located. If not provided, the function checks all bases. Defaults to None. :type base_name: str, optional :param time: The time at which to check for the Zone. If a specific time is not provided, the method will display the tree structure for the default time step. :type time: float, optional :returns: `True` if the CGNS tree has a Zone called `zone_name` in a Base called `base_name`, else return `False`. :rtype: bool .. py:method:: get_zone(zone_name: Optional[str] = None, base_name: Optional[str] = None, time: Optional[float] = None) -> plaid.types.CGNSNode Retrieve a CGNS Zone node by its name within a specific Base and time. :param zone_name: The name of the Zone node to retrieve. If not specified, checks that there is **at most** one zone in the base, else raises an error. Defaults to None. :type zone_name: str, optional :param base_name: The Base in which to seek to zone retrieve. If not specified, checks that there is **at most** one base, else raises an error. Defaults to None. :type base_name: str, optional :param time: Time at which you want to retrieve the Zone node. :type time: float, optional :returns: Returns a CGNS Zone node if found; otherwise, returns None. :rtype: CGNSNode .. py:method:: get_zone_type(zone_name: Optional[str] = None, base_name: Optional[str] = None, time: Optional[float] = None) -> str Get the type of a specific zone at a specified time. :param zone_name: The name of the zone whose type you want to retrieve. Default is None. :type zone_name: str, optional :param base_name: The name of the base in which the zone is located. Default is None. :type base_name: str, optional :param time: The timestamp for which you want to retrieve the zone type. Default is 0.0. :type time: float, optional :raises KeyError: Raised when the specified zone or base does not exist. You should first create the base/zone using `Sample.init_zone(zone_name, base_name)`. :returns: The type of the specified zone as a string. :rtype: str .. py:method:: get_nodal_tags(zone_name: Optional[str] = None, base_name: Optional[str] = None, time: Optional[float] = None) -> dict[str, plaid.types.Array] Get the nodal tags for a specified base and zone at a given time. :param zone_name: The name of the zone for which element connectivity data is requested. Defaults to None, indicating the default zone. :type zone_name: str, optional :param base_name: The name of the base for which element connectivity data is requested. Defaults to None, indicating the default base. :type base_name: str, optional :param time: The time at which element connectivity data is requested. If a specific time is not provided, the method will display the tree structure for the default time step. :type time: float, optional :returns: A dictionary where keys are nodal tags names and values are NumPy arrays containing the corresponding tag indices. The NumPy arrays have shape (num_nodal_tags). :rtype: dict[str, Array] .. py:method:: get_global(name: str, time: Optional[float] = None) -> Optional[plaid.types.Array] Retrieve a global array by name at a specified time. :param name: The name of the global array to retrieve. :type name: str :param time: The time step for which to retrieve the global array. If not provided, uses the default time. :type time: float, optional :returns: The global array if found, otherwise None. Returns a scalar if the array has size 1. :rtype: Optional[Array] .. py:method:: add_global(name: str, global_array: plaid.types.Array, time: Optional[float] = None) -> None Add or update a global array at a specified time. :param name: The name of the global array to add or update. :type name: str :param global_array: The array to store. :type global_array: Array :param time: The time step for which to add the global array. If not provided, uses the default time. :type time: float, optional .. note:: If the "Global" base does not exist, it will be created. If an array with the same name exists, its value will be updated. .. py:method:: del_global(name: str, time: Optional[float] = None) -> plaid.types.Array Delete a global array by name at a specified time. :param name: The name of the global array to delete. :type name: str :param time: The time step for which to delete the global array. If not provided, uses the default time. :type time: float, optional :raises KeyError: If the global array does not exist at the specified time. :returns: The value of the deleted global array. :rtype: Array .. py:method:: get_global_names(time: Optional[float] = None) -> list[str] Return a list of all global array names at the specified time(s). :param time: The time step for which to retrieve global names. If not provided, returns names for all available times. :type time: float, optional :returns: List of global array names (excluding "Time" arrays). :rtype: list[str] .. py:method:: get_nodes(zone_name: Optional[str] = None, base_name: Optional[str] = None, time: Optional[float] = None) -> Optional[plaid.types.Array] Get grid node coordinates from a specified base, zone, and time. :param zone_name: The name of the zone to search for. Defaults to None. :type zone_name: str, optional :param base_name: The name of the base to search for. Defaults to None. :type base_name: str, optional :param time: The time value to consider when searching for the zone. If a specific time is not provided, the method will display the tree structure for the default time step. :type time: float, optional :raises TypeError: Raised if multiple nodes are found. Only one is expected. :returns: A NumPy array containing the grid node coordinates. If no matching zone or grid coordinates are found, None is returned. :rtype: Optional[Array] Seealso: This function can also be called using `get_points()` or `get_vertices()`. .. py:attribute:: get_points .. py:attribute:: get_vertices .. py:method:: set_nodes(nodes: plaid.types.Array, zone_name: Optional[str] = None, base_name: Optional[str] = None, time: Optional[float] = None) -> None Set the coordinates of nodes for a specified base and zone at a given time. :param nodes: A numpy array containing the new node coordinates. :type nodes: Array :param zone_name: The name of the zone where the nodes should be updated. Defaults to None. :type zone_name: str, optional :param base_name: The name of the base where the nodes should be updated. Defaults to None. :type base_name: str, optional :param time: The time at which the node coordinates should be updated. If a specific time is not provided, the method will display the tree structure for the default time step. :type time: float, optional :raises KeyError: Raised if the specified base or zone do not exist. You should first :raises create the base and zone using the `Sample.init_zone(zone_name,base_name)` method.: Seealso: This function can also be called using `set_points()` or `set_vertices()` .. py:attribute:: set_points .. py:attribute:: set_vertices .. py:method:: get_elements(zone_name: Optional[str] = None, base_name: Optional[str] = None, time: Optional[float] = None) -> dict[str, plaid.types.Array] Retrieve element connectivity data for a specified zone, base, and time. :param zone_name: The name of the zone for which element connectivity data is requested. Defaults to None, indicating the default zone. :type zone_name: str, optional :param base_name: The name of the base for which element connectivity data is requested. Defaults to None, indicating the default base. :type base_name: str, optional :param time: The time at which element connectivity data is requested. If a specific time is not provided, the method will display the tree structure for the default time step. :type time: float, optional :returns: A dictionary where keys are element type names and values are NumPy arrays representing the element connectivity data. The NumPy arrays have shape (num_elements, num_nodes_per_element), and element indices are 0-based. :rtype: dict[str, Array] .. py:method:: get_field_names(location: str = None, zone_name: Optional[str] = None, base_name: Optional[str] = None, time: Optional[float] = None) -> list[str] Get a set of field names associated with a specified zone, base, location, and/or time. For each argument that is not specified, the method will search for fields in all available values for this argument. :param location: The desired grid location where to search for. Defaults to None. Possible values : :py:const:`plaid.constants.CGNS_FIELD_LOCATIONS` :type location: str, optional :param zone_name: The name of the zone to search for. Defaults to None. :type zone_name: str, optional :param base_name: The name of the base to search for. Defaults to None. :type base_name: str, optional :param time: The specific time at which to search for. Defaults to None. :type time: float, optional :returns: A set containing the names of the fields that match the specified criteria. :rtype: set[str] .. py:method:: get_field(name: str, location: str = 'Vertex', zone_name: Optional[str] = None, base_name: Optional[str] = None, time: Optional[float] = None) -> plaid.types.Field Retrieve a field with a specified name from a given zone, base, location, and time. :param name: The name of the field to retrieve. :type name: str :param location: The location at which to retrieve the field. Defaults to 'Vertex'. Possible values : :py:const:`plaid.constants.CGNS_FIELD_LOCATIONS` :type location: str, optional :param zone_name: The name of the zone to search for. Defaults to None. :type zone_name: str, optional :param base_name: The name of the base to search for. Defaults to None. :type base_name: str, optional :param time: The time value to consider when searching for the field. If a specific time is not provided, the method will display the tree structure for the default time step. :type time: float, optional :returns: A set containing the names of the fields that match the specified criteria. :rtype: Field .. py:method:: add_field(name: str, field: plaid.types.Field, location: str = 'Vertex', zone_name: Optional[str] = None, base_name: Optional[str] = None, time: Optional[float] = None, warning_overwrite: bool = True) -> None Add a field to a specified zone in the grid. :param name: The name of the field to be added. :type name: str :param field: The field data to be added. Integer arrays with dtype ``np.int32`` or ``np.int64`` are automatically converted to ``np.float64`` (with a warning) for CGNS compatibility. :type field: Field :param location: The grid location where the field will be stored. Defaults to 'Vertex'. Possible values : :py:const:`plaid.constants.CGNS_FIELD_LOCATIONS` :type location: str, optional :param zone_name: The name of the zone where the field will be added. Defaults to None. :type zone_name: str, optional :param base_name: The name of the base where the zone is located. Defaults to None. :type base_name: str, optional :param time: The time associated with the field. Defaults to 0. :type time: float, optional :param warning_overwrite: Show warning if a preexisting field is being overwritten. Defaults to True. :type warning_overwrite: bool, optional :raises KeyError: Raised if the specified zone does not exist in the given base. .. py:method:: del_field(name: str, location: str = 'Vertex', zone_name: Optional[str] = None, base_name: Optional[str] = None, time: Optional[float] = None) -> plaid.types.CGNSTree Delete a field with specified name in the mesh. :param name: The name of the field to be deleted. :type name: str :param location: The grid location where the field is stored. Defaults to 'Vertex'. Possible values : :py:const:`plaid.constants.CGNS_FIELD_LOCATIONS` :type location: str, optional :param zone_name: The name of the zone from which the field will be deleted. Defaults to None. :type zone_name: str, optional :param base_name: The name of the base where the zone is located. Defaults to None. :type base_name: str, optional :param time: The time associated with the field. Defaults to None. :type time: float, optional :raises KeyError: Raised if the specified zone or field does not exist in the given base. :returns: The tree at the provided time (without the deleted node) :rtype: CGNSTree .. py:method:: show_tree(time: Optional[float] = None) -> None Display the structure of the CGNS tree for a specified time. :param time: The time step for which you want to display the CGNS tree structure. Defaults to None. If a specific time is not provided, the method will display the tree structure for the default time step. :type time: float, optional