FieldsContainer#

class ansys.dpf.core.fields_container.FieldsContainer(fields_container=None, server=None)#

Bases: ansys.dpf.core.collection_base.CollectionBase[ansys.dpf.core.field.Field]

Represents a fields container, which contains fields belonging to a common result.

A fields container is a set of fields ordered by labels and IDs. Each field of the fields container has an ID for each label defining the given fields container. These IDs allow splitting the fields on any criteria.

The most common fields container has the label "time" with IDs corresponding to time sets. The label "complex", which is used in a harmonic analysis for example, allows real parts (id=0) to be separated from imaginary parts (id=1).

For more information, see the Fields container and fields documentation section.

Parameters:
  • fields_container (ansys.grpc.dpf.collection_message_pb2.Collection, ctypes.c_void_p,)

  • FieldsContainer – Fields container created from either a collection message or by copying an existing fields container. The default is “None``.

  • optional – Fields container created from either a collection message or by copying an existing fields container. The default is “None``.

  • server (ansys.dpf.core.server, optional) – Server with the channel connected to the remote or local instance. The default is None, in which case an attempt is made to use the global server.

Examples

Extract a displacement fields container from a transient result file.

>>> from ansys.dpf import core as dpf
>>> from ansys.dpf.core import examples
>>> transient = examples.download_transient_result()
>>> model = dpf.Model(transient)
>>> disp = model.results.displacement()
>>> disp.inputs.time_scoping.connect([1,5])
>>> fields_container = disp.outputs.fields_container()
>>> field_set_5 =fields_container.get_fields_by_time_complex_ids(5)
>>> #print(fields_container)

Create a fields container from scratch.

>>> from ansys.dpf import core as dpf
>>> fc= dpf.FieldsContainer()
>>> fc.labels =['time','complex']
>>> for i in range(0,20): #real fields
...     mscop = {"time":i+1,"complex":0}
...     fc.add_field(mscop,dpf.Field(nentities=i+10))
>>> for i in range(0,20): #imaginary fields
...     mscop = {"time":i+1,"complex":1}
...     fc.add_field(mscop,dpf.Field(nentities=i+10))

Overview#

create_subtype

Create a field subtype.

get_fields_by_time_complex_ids

Retrieve fields at a requested time ID or complex ID.

get_field_by_time_complex_ids

Retrieve a field at a requested time ID or complex ID.

get_fields

Retrieve the fields at a requested index or label space.

get_field

Retrieve the field at a requested index or label space.

get_field_by_time_id

Retrieve the complex field at a requested time.

get_imaginary_fields

Retrieve the complex fields at a requested time.

get_imaginary_field

Retrieve the complex field at a requested time.

add_field

Add or update a field at a requested label space.

add_field_by_time_id

Add or update a field at a requested time ID.

add_imaginary_field

Add or update an imaginary field at a requested time ID.

select_component

Select fields containing only the component index.

deep_copy

Create a deep copy of the fields container’s data (and its fields) on a given server.

get_time_scoping

Retrieve the time scoping containing the time sets.

plot

Plot the fields in the FieldsContainer for the given LabelSpace.

animate

Create an animation based on the Fields contained in the FieldsContainer.

set_labels

Set labels for scoping the collection.

add_label

Add the requested label to scope the collection.

has_label

Check if a collection has a specified label.

get_entries_indices

Retrieve the indices of the entries corresponding a requested label space .

get_label_space

Retrieve the label space of an entry at a requested index.

get_available_ids_for_label

Retrieve the IDs assigned to an input label.

get_label_scoping

Retrieve the scoping for an input label.

set_support

Set the support of the collection for a given label.

get_support

Get the support of the collection for a given label.

time_freq_support

Time frequency support.

name

Name of the Collection.

labels

Provides for getting scoping labels as a property.

integral_collection

Create a collection of integral type with a list.

__time_complex_label_space__

Return a label space dictionary mapping scoping to given id.

__getitem__

Retrieve the field at a requested index.

__add__

Add two fields or two fields containers.

__sub__

Subtract two fields or two fields containers.

__pow__

Compute element-wise field[i]^2.

__mul__

Multiply two fields or two fields containers.

__str__

Describe the entity.

__len__

Retrieve the number of entries.

__del__

Delete the entry.

__iter__

Provide for looping through entry items.

Import detail#

from ansys.dpf.core.fields_container import FieldsContainer

Property detail#

property FieldsContainer.time_freq_support#

Time frequency support.

property FieldsContainer.name#

Name of the Collection.

Notes

Available starting with DPF 2024 R2 pre0.

Return type:

str

property FieldsContainer.labels: List[str]#

Provides for getting scoping labels as a property.

Returns:

List of labels scoping the collection.

Return type:

List[str]

Attribute detail#

FieldsContainer.entries_type: type[TYPE] | None#
FieldsContainer.owned = False#

Method detail#

FieldsContainer.create_subtype(obj_by_copy)#

Create a field subtype.

FieldsContainer.get_fields_by_time_complex_ids(timeid=None, complexid=None)#

Retrieve fields at a requested time ID or complex ID.

Parameters:
  • timeid (int, optional) – Time ID or frequency ID, which is the one-based index of the result set.

  • complexid (int, optional) – Complex ID, where 1 is for imaginary and 0 is for real.

Returns:

fields – Fields corresponding to the request.

Return type:

list[Field]

Examples

Extract the fifth time set of a transient analysis.

>>> from ansys.dpf import core as dpf
>>> from ansys.dpf.core import examples
>>> transient = examples.download_transient_result()
>>> model = dpf.Model(transient)
>>> len(model.metadata.time_freq_support.time_frequencies)
35
>>> disp = model.results.displacement()
>>> disp.inputs.time_scoping.connect([1,5])
>>> fields_container = disp.outputs.fields_container()
>>> field_set_5 =fields_container.get_fields_by_time_complex_ids(5)
FieldsContainer.get_field_by_time_complex_ids(timeid=None, complexid=None)#

Retrieve a field at a requested time ID or complex ID.

An exception is raised if the number of fields matching the request is greater than one.

Parameters:
  • timeid (int, optional) – Time ID or frequency ID, which is the one-based index of the result set.

  • complexid (int, optional) – Complex ID, where 1 is for imaginary and 0 is for real.

Returns:

fields – Field corresponding to the request

Return type:

Field

Examples

Extract the fifth time set of a transient analysis.

>>> from ansys.dpf import core as dpf
>>> from ansys.dpf.core import examples
>>> transient = examples.download_transient_result()
>>> model = dpf.Model(transient)
>>> len(model.metadata.time_freq_support.time_frequencies)
35
>>> disp = model.results.displacement()
>>> disp.inputs.time_scoping.connect([1,5])
>>> fields_container = disp.outputs.fields_container()
>>> field_set_5 =fields_container.get_fields_by_time_complex_ids(5)
FieldsContainer.__time_complex_label_space__(timeid=None, complexid=None)#

Return a label space dictionary mapping scoping to given id.

Parameters:
  • timeid (int, optional) – time based id, by default None

  • complexid (int, optional) – complex id, by default None

Returns:

mapping of space type to given id.

Return type:

dict[str,int]

FieldsContainer.get_fields(label_space)#

Retrieve the fields at a requested index or label space.

Parameters:

label_space (dict[str,int]) – Scoping of the requested fields. For example, {"time": 1, "complex": 0}.

Returns:

fields – Fields corresponding to the request.

Return type:

list[Field]

Examples

>>> from ansys.dpf import core as dpf
>>> fc= dpf.FieldsContainer()
>>> fc.labels =['time','complex']
>>> #real fields
>>> for i in range(0,20):
...     mscop = {"time":i+1,"complex":0}
...     fc.add_field(mscop,dpf.Field(nentities=i+10))
>>> #imaginary fields
>>> for i in range(0,20):
...     mscop = {"time":i+1,"complex":1}
...     fc.add_field(mscop,dpf.Field(nentities=i+10))
>>> fields = fc.get_fields({"time":2})
>>> # imaginary and real fields of time 2
>>> len(fields)
2
FieldsContainer.get_field(label_space_or_index)#

Retrieve the field at a requested index or label space.

An exception is raised if the number of fields matching the request is greater than one.

Parameters:

label_space_or_index (dict[str,int], int) – Scoping of the requested fields. For example, {"time": 1, "complex": 0} or the index of the field.

Returns:

field – Field corresponding to the request.

Return type:

Field

Examples

>>> from ansys.dpf import core as dpf
>>> fc = dpf.fields_container_factory.over_time_freq_fields_container(
...     [dpf.Field(nentities=10)]
... )
>>> field = fc.get_field({"time":1})
FieldsContainer.get_field_by_time_id(timeid=None)#

Retrieve the complex field at a requested time.

Parameters:

timeid (int, optional) – Time ID, which is the one-based index of the result set.

Returns:

fields – Fields corresponding to the request.

Return type:

Field

FieldsContainer.get_imaginary_fields(timeid=None)#

Retrieve the complex fields at a requested time.

Parameters:

timeid (int, optional) – Time ID, which is the one-based index of the result set.

Returns:

fields – Fields corresponding to the request.

Return type:

list[Field]

FieldsContainer.get_imaginary_field(timeid=None)#

Retrieve the complex field at a requested time.

Parameters:

timeid (int, optional) – Time ID, which is the one-based index of the result set.

Returns:

fields – Field corresponding to the request.

Return type:

Field

FieldsContainer.__getitem__(key) ansys.dpf.core.field.Field#

Retrieve the field at a requested index.

Parameters:

key (int) – Index.

Returns:

field – Field corresponding to the request.

Return type:

Field

FieldsContainer.add_field(label_space, field)#

Add or update a field at a requested label space.

Parameters:
  • label_space (dict[str,int]) – Label space of the requested field. For example, {“time”:1, “complex”:0}.

  • field (Field) – DPF field to add or update.

Examples

>>> from ansys.dpf import core as dpf
>>> fc= dpf.FieldsContainer()
>>> fc.labels =['time','complex']
>>> for i in range(0,20): #real fields
...     mscop = {"time":i+1,"complex":0}
...     fc.add_field(mscop,dpf.Field(nentities=i+10))
>>> for i in range(0,20): #imaginary fields
...     mscop = {"time":i+1,"complex":1}
...     fc.add_field(mscop,dpf.Field(nentities=i+10))
FieldsContainer.add_field_by_time_id(field, timeid=1)#

Add or update a field at a requested time ID.

Parameters:
  • field (Field) – DPF field to add or update.

  • timeid (int, optional) – Time ID for the requested time set. The default is 1.

FieldsContainer.add_imaginary_field(field, timeid=1)#

Add or update an imaginary field at a requested time ID.

Parameters:
  • field (Field) – DPF field to add or update.

  • timeid (int, optional) – Time ID for the requested time set. The default is 1.

FieldsContainer.select_component(index)#

Select fields containing only the component index.

Fields can be selected only by component index as multiple fields may contain a different number of components.

Parameters:

index (int) – Index of the component.

Returns:

fields – Fields container with one component selected in each field.

Return type:

FieldsContainer

Examples

Select using a component index.

>>> from ansys.dpf import core as dpf
>>> from ansys.dpf.core import examples
>>> transient = examples.download_transient_result()
>>> model = dpf.Model(transient)
>>> disp = model.results.displacement()
>>> disp.inputs.time_scoping.connect([1,5])
>>> fields_container = disp.outputs.fields_container()
>>> disp_x_fields = fields_container.select_component(0)
>>> my_field = disp_x_fields[0]
FieldsContainer.deep_copy(server=None)#

Create a deep copy of the fields container’s data (and its fields) on a given server.

This method is useful for passing data from one server instance to another.

Parameters:

server (ansys.dpf.core.server, optional) – Server with the channel connected to the remote or local instance. The default is None, in which case an attempt is made to use the global server.

Returns:

fields_container_copy

Return type:

FieldsContainer

Examples

>>> from ansys.dpf import core as dpf
>>> from ansys.dpf.core import examples
>>> transient = examples.download_transient_result()
>>> model = dpf.Model(transient)
>>> disp = model.results.displacement()
>>> disp.inputs.time_scoping.connect([1,5])
>>> fields_container = disp.outputs.fields_container()
>>> other_server = dpf.start_local_server(as_global=False)
>>> deep_copy = fields_container.deep_copy(server=other_server)
FieldsContainer.get_time_scoping()#

Retrieve the time scoping containing the time sets.

Returns:

scoping – Scoping containing the time set IDs available in the fields container.

Return type:

Scoping

FieldsContainer.plot(label_space: dict = None, **kwargs)#

Plot the fields in the FieldsContainer for the given LabelSpace.

Check the labels available for the FieldsContainer with labels().

Parameters:
  • label_space – A dictionary (LabelSpace) of labels of the FieldsContainer with associated values to select for plotting. This is used to filter the data to plot, for example: - if label_space={'time': 10}: a single time step (mandatory for transient) - if label_space={'complex': 0, 'part': 12}: real part of complex data for a part See get_fields(). If None is given, it renders all fields available, which may not make sense.

  • **kwargs – For more information on accepted keyword arguments, see plot() and DpfPlotter.

FieldsContainer.animate(save_as: str = None, deform_by: FieldsContainer | ansys.dpf.core.Result | ansys.dpf.core.Operator = None, scale_factor: float | Sequence[float] = 1.0, shell_layer: ansys.dpf.core.common.shell_layers = shell_layers.top, **kwargs)#

Create an animation based on the Fields contained in the FieldsContainer.

This method creates a movie or a gif based on the time ids of a FieldsContainer. For kwargs see pyvista.Plotter.open_movie/add_text/show.

Parameters:
  • save_as – Path of file to save the animation to. Defaults to None. Can be of any format supported by pyvista.Plotter.write_frame (.gif, .mp4, …).

  • deform_by – Used to deform the plotted mesh. Must return a FieldsContainer of the same length as self, containing 3D vector Fields of distances. Defaults to None, which takes self if possible. Set as False to force static animation.

  • scale_factor (float, list, optional) – Scale factor to apply when warping the mesh. Defaults to 1.0. Can be a list to make scaling frequency-dependent.

  • shell_layer – Enum used to set the shell layer if the field to plot contains shell elements. Defaults to top layer.

  • **kwargs – Additional keyword arguments for the animator. Used by pyvista.Plotter() (off_screen, cpos, …), or by pyvista.Plotter.open_movie() (framerate, quality, …)

FieldsContainer.__add__(fields_b)#

Add two fields or two fields containers.

Returns:

add

Return type:

operators.math.add_fc

FieldsContainer.__sub__(fields_b)#

Subtract two fields or two fields containers.

Returns:

minus

Return type:

operators.math.minus_fc

FieldsContainer.__pow__(value)#

Compute element-wise field[i]^2.

FieldsContainer.__mul__(value)#

Multiply two fields or two fields containers.

Returns:

mul

Return type:

operators.math.generalized_inner_product_fc

static FieldsContainer.integral_collection(inpt, server: ansys.dpf.core.server_types.BaseServer = None)#

Create a collection of integral type with a list.

The collection of integral is the equivalent of an array of data sent server side. It can be used to efficiently stream large data to the server.

Parameters:

inpt (list[float], list[int], numpy.array) – list to transfer server side

Return type:

IntegralCollection

Notes

Used by default by the 'Operator' and the``’Workflow’`` when a list is connected or returned.

FieldsContainer.set_labels(labels)#

Set labels for scoping the collection.

Parameters:

labels (list[str], optional) – Labels to scope entries to. For example, ["time", "complex"].

FieldsContainer.add_label(label, default_value=None)#

Add the requested label to scope the collection.

Parameters:
  • label (str) – Labels to scope the entries to. For example, "time".

  • default_value (int, optional) – Default value for existing fields in the collection. The default is None.

Examples

>>> from ansys.dpf import core as dpf
>>> coll = dpf.FieldsContainer()
>>> coll.add_label('time')
FieldsContainer.has_label(label) bool#

Check if a collection has a specified label.

Parameters:

label (str) – Label to search for. For example, "time".

Returns:

True when successful, False when failed.

Return type:

bool

Examples

>>> from ansys.dpf import core as dpf
>>> coll = dpf.FieldsContainer()
>>> coll.add_label('time')
>>> coll.has_label('time')
True
>>> coll.has_label('complex')
False
FieldsContainer.get_entries_indices(label_space)#

Retrieve the indices of the entries corresponding a requested label space .

Notes

Available starting with DPF 2025R1.

Parameters:

label_space (dict[str,int]) – Label space or index. For example, {"time": 1, "complex": 0} or the index of the field.

Returns:

indices – Indices of the entries corresponding to the request.

Return type:

list[int], list[Field], list[MeshedRegion]

FieldsContainer.get_label_space(index)#

Retrieve the label space of an entry at a requested index.

Parameters:

index (int) – Index of the entry.

Returns:

label_space – Scoping of the requested entry. For example, {"time": 1, "complex": 0}.

Return type:

dict(str:int)

FieldsContainer.get_available_ids_for_label(label='time')#

Retrieve the IDs assigned to an input label.

Parameters:

label (str) – Name of the input label. The default is "time".

Returns:

ids – List of IDs assigned to the input label.

Return type:

list[int]

FieldsContainer.get_label_scoping(label='time')#

Retrieve the scoping for an input label.

This method allows you to retrieve a list of IDs for a given input label in the collection. For example, if the label el_type exists in the collection, you can use the get_lable_scoping method to retrieve a list of IDS with this label. You can then use these IDs to request a given entity inside the collection.

Parameters:

label (str) – Name of the input label.

Returns:

scoping – IDs scoped to the input label.

Return type:

Scoping

FieldsContainer.set_support(label: str, support: ansys.dpf.core.support.Support) None#

Set the support of the collection for a given label.

Notes

Available starting with DPF 2023 R1.

FieldsContainer.get_support(label: str) ansys.dpf.core.support.Support#

Get the support of the collection for a given label.

Notes

Available starting with DPF 2023 R1.

FieldsContainer.__str__()#

Describe the entity.

Returns:

description – Description of the entity.

Return type:

str

FieldsContainer.__len__()#

Retrieve the number of entries.

FieldsContainer.__del__()#

Delete the entry.

FieldsContainer.__iter__()#

Provide for looping through entry items.