ansys.dpf.core.Field#

class ansys.dpf.core.Field(nentities=0, nature=natures.vector, location=locations.nodal, field=None, server=None)#

Bases: ansys.dpf.core.field_base._FieldBase

Represents the main simulation data container.

This can be evaluated data from the Operator class or created by a factory and directly by an instance of this class.

A field’s data is always associated to its scoping (entities associated to each value) and support (subset of the model where the data is), making the field a self-describing piece of data.

The field’s scoping defines the order of the data, for example: the first ID in the scoping identifies to which entity the first entity data belongs.

The minimum requirement for a well defined field is for it to have a dimensionality (scalar, three components vector, six components symmetrical matrix, and so on), a location (“Nodal”, “Elemental”, “ElementalNodal”, “TimeFreq”), a data vector, and a scoping with IDs. You can also set the number of shell layers. If the field has one elementary data by entity (elementary data size equals the number of components for “Nodal” or “Elemental” field for example), then the data vector can be set directly. If a more complex field is required (“ElementalNodal” field for example), the data can be set entity by entity.

For more information, see Fields container and fields.

Parameters:

nentities (int, optional) – Number of entities reserved. The default is 0.
nature (ansys.dpf.core.common.natures, optional) – Nature of the field.
location (str, optional) –
Location of the field. Options are in locations
- dpf.locations.nodal
- dpf.locations.elemental
- dpf.locations.elemental_nodal
- …
field (Field, ansys.grpc.dpf.field_pb2.Field, ctypes.c_void_p, optional) – Field message generated from a gRPC stub, or returned by DPF’s C clients.
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

Create a field from scratch.

>>> from ansys.dpf.core import locations
>>> from ansys.dpf import core as dpf
>>> field_with_classic_api = dpf.Field()
>>> field_with_classic_api.location = locations.nodal

Create a symmetrical matrix elemental field from scratch.

>>> from ansys.dpf import core as dpf
>>> num_entities = 2
>>> my_field = dpf.Field(num_entities, dpf.natures.symmatrix, locations.elemental)
>>> my_scoping = dpf.Scoping(location=locations.elemental, ids=[1, 2])
>>> my_field.scoping = my_scoping

Add all the data at once.

>>> from ansys.dpf import core as dpf
>>> my_data = [1.0,1.0,1.0,0.0,0.0,0.0,1.0,1.0,1.0,0.0,0.0,0.0]
>>> my_field.data = my_data

Add data entity by entity.

>>> from ansys.dpf import core as dpf
>>> my_elem_data = [1.0,1.0,1.0,0.0,0.0,0.0]
>>> my_field.append(my_elem_data, scopingid=1)
>>> my_field.append(my_elem_data, scopingid=2)

Create a nodal scalar field using the fields factory.

>>> from ansys.dpf.core import fields_factory
>>> from ansys.dpf import core as dpf
>>> my_scalar_field = fields_factory.create_scalar_field(num_entities=2, location=locations.nodal)
>>> my_scalar_field.data = [1.0, 3.0]

Extract a displacement field 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()
>>> fields_container = disp.outputs.fields_container()
>>> field = fields_container[0]
>>> len(field)
11460
>>> field.component_count
3
>>> field.elementary_data_count
3820

Create a displacement field.

>>> from ansys.dpf import core as dpf
>>> import numpy as np
>>> my_field = dpf.Field(10, dpf.natures.vector,dpf.locations.nodal)
>>> my_field.data = np.zeros(30)
>>> my_field.scoping.ids = range(1,11)

Set data.

>>> 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()
>>> fields_container = disp.outputs.fields_container()
>>> field = fields_container[0]
>>> field.data[2]
DPFArray([-0.00672665, -0.03213735,  0.00016716]...

Accessing data with a custom order.

>>> from ansys.dpf import core as dpf
>>> from ansys.dpf.core import examples
>>> transient = examples.download_transient_result()
>>> model = dpf.Model(transient)
>>> ids_order = [2,3]
>>> stress = model.results.stress(mesh_scoping=dpf.Scoping(
...     ids=ids_order, location=dpf.locations.nodal))
>>> fields_container = stress.outputs.fields_container()
>>> field = fields_container[0]
>>> field.scoping.ids
DPFArray([3, 2]...
>>> field.data
DPFArray([[  3755059.33333333,  -2398534.3515625 , -27519072.33333333,
             2194748.65625   ,   8306637.58333333,   2018637.03125   ],
          [  2796852.09375   ,   -992492.62304688,  22519752.625     ,
            -1049027.46875   ,  10846776.1875    ,   4119072.3125    ]]...
>>> field.get_entity_data_by_id(2)
DPFArray([[ 2796852.09375   ,  -992492.62304688, 22519752.625     ,
           -1049027.46875   , 10846776.1875    ,  4119072.3125    ]]...
>>> field.get_entity_data_by_id(3)
DPFArray([[  3755059.33333333,  -2398534.3515625 , -27519072.33333333,
             2194748.65625   ,   8306637.58333333,   2018637.03125   ]]...

_field_definition#

property _api: ansys.dpf.gate.field_abstract_api.FieldAbstractAPI#

_init_api_env()#

static _field_create_internal_obj(api: ansys.dpf.gate.field_abstract_api.FieldAbstractAPI, client, nature, nentities, location=locations.nodal, ncomp_n=0, ncomp_m=0, with_type=None)#

Return a gRPC field message or C object instance of a new field.

This new field is created with this functions parameter attributes

Parameters:

client (None, GrpcClient, GrpcServer)
snature (str) –
Nature of the field entity data. For example:
- ansys.dpf.core.natures.matrix
- ansys.dpf.core.natures.scalar
num_entities (int) – Number of entities to reserve.
location (str, optional) –
Location of the field. For example:
- ansys.dpf.core.natures.nodal ("Nodal")
- ansys.dpf.core.natures.elemental ("Elemental")
- ansys.dpf.core.natures.elemental_nodal ("ElementalNodal")
- …
ncomp_n (int) – Number of lines.
ncomp_m (int) – Number of columns.

Returns:

field – DPF field in the requested format.

Return type:

field_pb2.Field or ctypes.void_p

as_local_field()#

Create a deep copy of the field that can be accessed and modified locally.

This method allows you to access and modify the local copy of the field without sending a request to the server. It should be used in a with statement so that the local field is released and the data is sent to the server in one action. If it is not used in a with statement, Field.release_data() should be used to update the field.

Warning

If this as_local_field method is not used as a context manager in a with statement or if the method release_data() is not called, the data will not be updated.

Returns:: local_field
Return type:: Field

Examples

>>> from ansys.dpf import core as dpf
>>> num_entities = 3
>>> field_to_local = dpf.fields_factory.create_3d_vector_field(num_entities, location=dpf.locations.elemental_nodal)
>>> with field_to_local.as_local_field() as f:
...     for i in range(1,num_entities+1):
...         f.append([[0.1*i,0.2*i, 0.3*i],[0.1*i,0.2*i, 0.3*i]],i)
...         f.get_entity_data(i-1),[[0.1*i,0.2*i, 0.3*i],[0.1*i,0.2*i, 0.3*i]]
(DPFArray([[0.1, 0.2, 0.3],
          [0.1, 0.2, 0.3]]), [[0.1, 0.2, 0.3], [0.1, 0.2, 0.3]])
(DPFArray([[0.2, 0.4, 0.6],
          [0.2, 0.4, 0.6]]), [[0.2, 0.4, 0.6], [0.2, 0.4, 0.6]])
(DPFArray([[0.3, 0.6, 0.9],
          [0.3, 0.6, 0.9]]), [[0.30000000000000004, 0.6000000000000001, 0.8999999999999999], [0.30000000000000004, 0.6000000000000001, 0.8999999999999999]])

property location#

Field location.

Returns:: Location string, Options are in locations.
Return type:: str

Examples

Location for a stress field evaluated at nodes.

>>> from ansys.dpf import core as dpf
>>> from ansys.dpf.core import examples
>>> model = dpf.Model(examples.download_transient_result())
>>> s_op = model.results.stress()
>>> s_fc = s_op.outputs.fields_container()
>>> field = s_fc[0]
>>> field.location
'ElementalNodal'

property component_count#: Number of components.

property elementary_data_count#: Number of elementary data.

property size#: Size of data.

_set_scoping(scoping)#

Set the scoping.

Parameters:: scoping (ansys.dpf.core.scoping.Scoping)

_get_scoping()#

Retrieve the scoping.

Returns:: scoping
Return type:: ansys.dpf.core.scoping.Scoping

property shell_layers#

Order of the shell layers.

Return type:: ansys.dpf.core.common.shell_layers

get_entity_data(index: int) → ansys.dpf.gate.dpf_array.DPFArray#: Retrieve entity data by index.

get_entity_data_by_id(id: int) → ansys.dpf.gate.dpf_array.DPFArray#: Retrieve entity data by id.

append(data, scopingid)#: Append data to the Field.

_get_data_pointer()#

First index of each entity data.

Returns:: Data in the field.
Return type:: numpy.ndarray

Notes

Print a progress bar.

_set_data_pointer(data)#

_get_data(np_array=True)#

_set_data(data)#

to_nodal()#

Convert the field to one with a Nodal location.

This method is valid only when the field’s current location is ElementalNodal or Elemental.

Returns:: nodal_field – with location=='Nodal'.
Return type:: Field

plot(shell_layers: ansys.dpf.core.common.shell_layers = None, deform_by: Field | ansys.dpf.core.results.Result | ansys.dpf.core.dpf_operator.Operator = None, scale_factor: float = 1.0, meshed_region: ansys.dpf.core.meshed_region.MeshedRegion = None, **kwargs)#

Plot the field or fields container on the mesh support if it exists.

Warning

This method is primarily added out of convenience as plotting directly from the field can be slower than extracting the meshed region and plotting the field on top of that. It is more efficient to plot with:

>>> from ansys.dpf import core as dpf
>>> from ansys.dpf.core import examples
>>> transient = examples.download_transient_result()
>>> model = dpf.Model(transient)
>>> mesh = model.metadata.meshed_region
>>> disp = model.results.displacement()
>>> fields_container = disp.outputs.fields_container()
>>> field = fields_container[0]
>>> mesh.plot(field)

Parameters:

shell_layers – Enum used to set the shell layers if the model to plot contains shell elements. Defaults to the top layer.
deform_by – Used to deform the plotted mesh. Must output a 3D vector field.
scale_factor – Scaling factor to apply when warping the mesh.
meshed_region – Mesh to plot the field on.
**kwargs – Additional keyword arguments for the plotter. For additional keyword arguments, see help(pyvista.plot).

resize(nentities, datasize)#

Allocate memory.

Parameters:

nentities (int) – Number of IDs in the scoping.
datasize (int) – Size of the data vector.

_load_field_definition()#: Attempt to load the field definition for this field.

property unit#

Units for the field.

Returns:: Units for the field.
Return type:: str

Examples

Units for a displacement field.

>>> from ansys.dpf import core as dpf
>>> my_field = dpf.Field(10, dpf.natures.vector,dpf.locations.nodal)
>>> my_field.unit = "m"
>>> my_field.unit
'm'

property dimensionality#

Dimensionality represents the shape of the elementary data contained in the field.

Returns:: dimensionality – Nature and size of the elementary data.
Return type:: ansys.dpf.core.dimensionality.Dimensionality

property name#: Name of the field.

_set_field_definition(field_definition)#

Set the field definition.

Parameters:: field_definition (:class”ansys.dpf.core.field_definition.FieldDefinition)

property field_definition#

Field information, including its location, unit, dimensionality, and shell layers.

Return type:: ansys.dpf.core.field_definition.FieldDefinition

_get_meshed_region() → ansys.dpf.core.meshed_region.MeshedRegion#

Retrieve the meshed region.

Return type:: ansys.dpf.core.meshed_region.MeshedRegion

_get_time_freq_support()#

Retrieve the time frequency support.

Return type:: ansys.dpf.core.time_freq_support.TimeFreqSupport

_set_support(support, support_type: str)#

property time_freq_support#

Time frequency support of the field.

Return type:: ansys.dpf.core.time_freq_support.TimeFreqSupport

property meshed_region: ansys.dpf.core.meshed_region.MeshedRegion#

Meshed region of the field.

Return type:: ansys.dpf.core.meshed_region.MeshedRegion

__add__(field_b)#

Add two fields.

Return type:: ansys.dpf.core.operators.math.add.add

__pow__(value)#: Compute element-wise field[i]^2.

__mul__(value)#

Multiplies two fields.

Return type:: ansys.dpf.core.operators.math.generalized_inner_product.generalized_inner_product

__sub__(fields_b)#

Subtract two fields.

Return type:: ansys.dpf.core.operators.math.minus.minus

_min_max()#

min()#

Retrieve the component-wise minimum over this field.

Returns:: min – Component-wise minimum field.
Return type:: Field

max()#

Retrieve the component-wise maximum over this field.

Returns:: max – Component-wise maximum field.
Return type:: Field

deep_copy(server=None)#

Create a deep copy of the field’s data on a given server.

This method can be 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:: field_copy
Return type:: Field

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()
>>> fields_container = disp.outputs.fields_container()
>>> field = fields_container[0]
>>> other_server = dpf.start_local_server(as_global=False)
>>> deep_copy = field.deep_copy(server=other_server)