Arcane  4.1.12.0
User documentation
Loading...
Searching...
No Matches
Arcane::IItemFamily Class Referenceabstract

Interface of an entity family. More...

#include <arcane/core/IItemFamily.h>

Public Member Functions

virtual void build ()=0
virtual String name () const =0
 Family name.
virtual String fullName () const =0
 Full family name (with the mesh's name).
virtual eItemKind itemKind () const =0
 Entity kind.
virtual Integer nbItem () const =0
 Number of entities.
virtual Int32 maxLocalId () const =0
virtual ItemInternalArrayView itemsInternal ()=0
 Internal array of entities.
virtual ItemInfoListView itemInfoListView ()=0
 View on the entity information list.
virtual IItemFamilyparentFamily () const =0
 IItemFamily parent.
virtual void setParentFamily (IItemFamily *parent)=0
virtual Integer parentFamilyDepth () const =0
 Gives the nesting depth of the current mesh.
virtual void addChildFamily (IItemFamily *family)=0
virtual IItemFamilyCollection childFamilies ()=0
 Child families of this family.
virtual VariableItemInt32itemsNewOwner ()=0
 Variable containing the number of the new subdomain owning the entity.
virtual void checkValid ()=0
 Check the validity of internal structures (internal).
virtual void checkValidConnectivity ()=0
 Verification of the validity of internal structures concerning connectivity.
virtual void checkUniqueIds (Int64ConstArrayView unique_ids)=0
 Checks that the unique_ids are truly unique for all subdomains.
virtual ItemVectorView view (Int32ConstArrayView local_ids)=0
 View on the entities.
virtual ItemVectorView view ()=0
 View on all entities in the family.
virtual void removeItems2 (mesh::ItemDataList &item_data_list)=0
 Removes entities.
virtual void removeNeedRemoveMarkedItems ()=0
virtual ItemInternalfindOneItem (Int64 unique_id)=0
 Unique ID entity unique_id.
virtual void endUpdate ()=0
 Notifies the end of modification of the entity list.
virtual void partialEndUpdate ()=0
 Partial update.
virtual void partialEndUpdateGroup (const ItemGroup &group)=0
 Updates a group.
virtual void partialEndUpdateVariable (IVariable *variable)=0
 Updates a variable.
virtual void notifyItemsOwnerChanged ()=0
 Notifies that the entities specific to the family's subdomain have been modified.
virtual void notifyItemsUniqueIdChanged ()=0
 Notifies that the unique IDs of the entities have been modified.
virtual IItemConnectivityInfolocalConnectivityInfos () const =0
 Information on local connectivity within the subdomain for this family.
virtual IItemConnectivityInfoglobalConnectivityInfos () const =0
 Information on global connectivity across all subdomains.
virtual void setHasUniqueIdMap (bool v)=0
 Indicates whether the family has a conversion table from uniqueId to localId.
virtual bool hasUniqueIdMap () const =0
 Indicates if the family has a uniqueId to localId conversion table.
virtual void itemsUniqueIdToLocalId (Int32ArrayView local_ids, Int64ConstArrayView unique_ids, bool do_fatal=true) const =0
 Converts an array of unique numbers to local numbers.
virtual void itemsUniqueIdToLocalId (Int32ArrayView local_ids, ConstArrayView< ItemUniqueId > unique_ids, bool do_fatal=true) const =0
 Converts an array of unique numbers to local numbers.
virtual void setItemSortFunction (IItemInternalSortFunction *sort_function)=0
 Positions the entity sorting function.
virtual IItemInternalSortFunctionitemSortFunction () const =0
 Entity sorting function.
virtual ISubDomainsubDomain () const =0
 Associated sub-domain.
virtual ITraceMngtraceMng () const =0
 Associated trace manager.
virtual IMeshmesh () const =0
 Associated mesh.
virtual IParallelMngparallelMng () const =0
 Associated parallelism manager.
virtual ItemGroup allItems () const =0
 Group of all entities.
virtual ItemGroupCollection groups () const =0
 Collection of groups in this family.
operations on groups
virtual ItemGroup findGroup (const String &name) const =0
 Searches for a group.
virtual ItemGroup findGroup (const String &name, bool create_if_needed)=0
 Searches for a group.
virtual ItemGroup createGroup (const String &name, Int32ConstArrayView local_ids, bool do_override=false)=0
 Creates an entity group named name containing the entities local_ids.
virtual ItemGroup createGroup (const String &name)=0
 Creates an entity group named name.
virtual void destroyGroups ()=0
 Deletes all groups in this family.
virtual ItemGroup createGroup (const String &name, const ItemGroup &parent, bool do_override=false)=0
virtual IVariablefindVariable (const String &name, bool throw_exception=false)=0
 Searches for the variable name name associated with this family.
virtual void usedVariables (VariableCollection collection)=0
 Adds the list of variables used by this family to the collection.
virtual void prepareForDump ()=0
 Prepares data for dumping.
virtual void readFromDump ()=0
 Reads data from a dump.
virtual void copyItemsValues (Int32ConstArrayView source, Int32ConstArrayView destination)=0
virtual void copyItemsMeanValues (Int32ConstArrayView first_source, Int32ConstArrayView second_source, Int32ConstArrayView destination)=0
virtual void clearItems ()=0
 Deletes all entities in the family.
virtual void compactItems (bool do_sort)=0
 Compresses the entities.
virtual void computeSynchronizeInfos ()=0
 Constructs the structures necessary for synchronization.
virtual void getCommunicatingSubDomains (Int32Array &sub_domains) const =0
 List of communicating sub-domains for the entities.
variable synchronization operations
virtual IVariableSynchronizerallItemsSynchronizer ()=0
 Synchronizer on all entities of the family.
virtual void synchronize (VariableCollection variables)=0
 Synchronizes the variables variables.
virtual void synchronize (VariableCollection variables, Int32ConstArrayView local_ids)
 Synchronizes the variables variables on a list of entities.
virtual void reduceFromGhostItems (IVariable *v, IDataOperation *operation)=0
 Applies a reduction operation from ghost items.
virtual void reduceFromGhostItems (IVariable *v, Parallel::eReduceType operation)=0
 Applies a reduction operation from ghost items.
virtual ItemPairGroup findAdjencyItems (const ItemGroup &group, const ItemGroup &sub_group, eItemKind link_kind, Integer nb_layer)=0
 Searches for an adjacency list.
virtual ItemPairGroup findAdjacencyItems (const ItemGroup &group, const ItemGroup &sub_group, eItemKind link_kind, Integer nb_layer)
 Searches for an adjacency list.
virtual IParticleFamilytoParticleFamily ()=0
 Returns the interface of the particle family for this family.
virtual IDoFFamilytoDoFFamily ()
 Returns the interface of the particle family for this family.
virtual void internalRemoveItems (Int32ConstArrayView local_ids, bool keep_ghost=false)=0
Register/Delete a connectivity manager.

Allows propagating family changes to "external" connectivities in which it is involved. These "external" connectivities are currently those using degrees of freedom.

Note
These methods are internal to Arcane.
virtual void addSourceConnectivity (IItemConnectivity *connectivity)=0
virtual void addTargetConnectivity (IItemConnectivity *connectivity)=0
virtual void removeSourceConnectivity (IItemConnectivity *connectivity)=0
virtual void removeTargetConnectivity (IItemConnectivity *connectivity)=0
virtual void setConnectivityMng (IItemConnectivityMng *connectivity_mng)=0
virtual void addGhostItems (Int64ConstArrayView unique_ids, Int32ArrayView items, Int32ConstArrayView owners)=0
 Allocates ghost entities.
virtual IItemFamilyPolicyMngpolicyMng ()=0
 Interface of behaviors/policies associated with this family.
virtual Propertiesproperties ()=0
 Properties associated with this family.
virtual EventObservableView< const ItemFamilyItemListChangedEventArgs & > itemListChangedEvent ()=0
 Event for entity addition and deletion.
virtual void experimentalChangeUniqueId (ItemLocalId local_id, ItemUniqueId unique_id)=0
 Changes the unique number of the entity.
virtual void resizeVariables (bool force_resize)=0
 Resizes the variables of this family.
virtual IItemFamilyTopologyModifier_topologyModifier ()=0
 Topology modifier interface.
virtual IItemFamilyInternal * _internalApi ()=0
 Internal Arcane API.

Detailed Description

Interface of an entity family.

An entity family manages all entities of the same kind (Item::kind()) and is attached to a mesh (IMesh).

For any mesh, there is exactly one family of nodes (Node), edges (Edge), faces (Face), and cells (Cell). These entities are called base mesh entities and the associated families are the base mesh families.

Depending on the implementation, there may also be families of particles (Particle), dual nodes (DualNode), or links (Link). Depending on the requested connectivity, a family may not have elements. For example, by default in 3D, edges (Edge) are not created.

Each entity in the family has a local identifier within the family, given by Item::localId(). When a family evolves, this identifier may be modified. The Item::localId() of entities in a family are not necessarily contiguous. The maxLocalId() method allows knowing the maximum of these values. Compaction ensures that the localId() are renumbered from 0 to (nbItem()-1). For base mesh entities, compaction is automatic if the mesh has the property "sort" set to true. For others, you must call compactItems().

By default, a family has a conversion table from uniqueId() to localId(). This table must exist to allow the following operations:

  • the uniqueId() is guaranteed to be unique within the subdomain and must be so by construction across all subdomains.
  • calling the itemsUniqueIdToLocalId() methods.
  • the family entities can be present in multiple subdomains.
  • performing synchronizations.
  • having partial variables on this family

It is possible to enable or disable this conversion table via the setHasUniqueIdMap() method only if no entity has been created. This operation is not possible on node, edge, face, and cell families.

When a family is modified by adding or removing entities, the variables and groups relying on this family are no longer usable until endUpdate() is called. For optimization reasons, it is possible to perform updates of certain variables or groups via partialEndUpdateVariable() or partialEndUpdateGroup(). ATTENTION, an call to one of these 3 update methods invalidates the entity instances (Item). To retain a reference to an entity, you must either use a group (ItemGroup) or keep its unique number and use itemsUniqueIdToLocalId().

Definition at line 82 of file IItemFamily.h.

Constructor & Destructor Documentation

◆ ~IItemFamily()

virtual Arcane::IItemFamily::~IItemFamily ( )
inlinevirtual

Definition at line 89 of file IItemFamily.h.

Member Function Documentation

◆ addGhostItems()

virtual void Arcane::IItemFamily::addGhostItems ( Int64ConstArrayView unique_ids,
Int32ArrayView items,
Int32ConstArrayView owners )
pure virtual

Allocates ghost entities.

After calling this operation, you must call endUpdate() to notify the instance that the modifications are finished. It is possible to chain several allocations before calling endUpdate().

The unique_ids are those of items present on another sub-domain, whose number is in the owners array (of the same size as the unique_ids array). items must have the same number of elements as unique_ids and will be filled back with the local numbers of the created entities.

◆ checkUniqueIds()

virtual void Arcane::IItemFamily::checkUniqueIds ( Int64ConstArrayView unique_ids)
pure virtual

Checks that the unique_ids are truly unique for all subdomains.

This method DOES NOT check that the unique_ids are identical to those of entities already created. It only checks the set of unique_ids passed as arguments by all subdomains.

This operation is collective and must be called by all subdomains.

◆ clearItems()

virtual void Arcane::IItemFamily::clearItems ( )
pure virtual

Deletes all entities in the family.

Warning
be careful not to destroy entities that are used in by another family. In general, it is safer to use IMesh::clearItems() if you want to delete all elements of the mesh.

References clearItems().

Referenced by clearItems().

◆ computeSynchronizeInfos()

virtual void Arcane::IItemFamily::computeSynchronizeInfos ( )
pure virtual

Constructs the structures necessary for synchronization.

This operation must be performed every time the entities of the mesh change ownership (for example, during a load balancing).

This operation is collective.

References computeSynchronizeInfos().

Referenced by computeSynchronizeInfos().

◆ copyItemsMeanValues()

virtual void Arcane::IItemFamily::copyItemsMeanValues ( Int32ConstArrayView first_source,
Int32ConstArrayView second_source,
Int32ConstArrayView destination )
pure virtual

Copies the mean values of entities numbered first_source and second_source into entities numbered destination

Parameters
first_sourcelist of localIds of the 1st source
second_sourcelist of localIds of the 2nd source
destinationlist of destination localIds

References copyItemsMeanValues().

Referenced by copyItemsMeanValues().

◆ copyItemsValues()

virtual void Arcane::IItemFamily::copyItemsValues ( Int32ConstArrayView source,
Int32ConstArrayView destination )
pure virtual

Copies the values of entities numbered source into entities numbered destination

Parameters
sourcelist of source localIds
destinationlist of destination localIds

References copyItemsValues().

Referenced by copyItemsValues().

◆ createGroup() [1/2]

virtual ItemGroup Arcane::IItemFamily::createGroup ( const String & name)
pure virtual

Creates an entity group named name.

The group must not already exist, otherwise an exception is raised.

Parameters
namename of the group
Returns
the created group

References createGroup(), and name().

◆ createGroup() [2/2]

virtual ItemGroup Arcane::IItemFamily::createGroup ( const String & name,
Int32ConstArrayView local_ids,
bool do_override = false )
pure virtual

Creates an entity group named name containing the entities local_ids.

Parameters
namename of the group
local_idslist of localId() of the entities composing the group.
do_overrideif true and a group of the same name already exists, its elements are replaced by those given in local_ids. If false, an exception is raised.
Returns
the created group

References createGroup(), and name().

Referenced by createGroup(), createGroup(), Arcane::ItemGroupImpl::createSubGroup(), and destroyGroups().

◆ endUpdate()

virtual void Arcane::IItemFamily::endUpdate ( )
pure virtual

Notifies the end of modification of the entity list.

This method must be called after modifying the entity list (after adding or removing). It updates the groups and resizes the variables on this family.

References endUpdate().

Referenced by endUpdate().

◆ experimentalChangeUniqueId()

virtual void Arcane::IItemFamily::experimentalChangeUniqueId ( ItemLocalId local_id,
ItemUniqueId unique_id )
pure virtual

Changes the unique number of the entity.

Warning
This method is experimental.
Modifying an entity's uniqueId can cause inconsistencies in the mesh and numbering. It is preferable to only call this method on entities that are not associated with others (for example, nodes that have just been created).

◆ findAdjacencyItems()

ItemPairGroup Arcane::IItemFamily::findAdjacencyItems ( const ItemGroup & group,
const ItemGroup & sub_group,
eItemKind link_kind,
Integer nb_layer )
virtual

Searches for an adjacency list.

Searches for the list of entities of type sub_kind, linked by the entity type link_kind of group group, over a number of layers nb_layer.

If group and sub_group are of the same kind, an entity is always in its adjacency list, as the first element.

If the list does not exist, it is created.

Note
currently only one layer is allowed.

Definition at line 337 of file InterfaceImpl.cc.

References findAdjencyItems().

Referenced by findAdjencyItems(), and Arcane::ItemPairGroup::ItemPairGroup().

◆ findGroup() [1/2]

virtual ItemGroup Arcane::IItemFamily::findGroup ( const String & name) const
pure virtual

Searches for a group.

Parameters
namename of the group to search for
Returns
the group named name or a null group if none exists.

References findGroup(), and name().

Referenced by ItemGroupBuilder< T >::buildGroup(), findGroup(), and findGroup().

◆ findGroup() [2/2]

virtual ItemGroup Arcane::IItemFamily::findGroup ( const String & name,
bool create_if_needed )
pure virtual

Searches for a group.

Parameters
namename of the group to search for
Returns
the found group or a null group if no group with the name name and type type exists and if create_if_needed is false. If create_if_needed is true, an empty group named name is created and returned.

References findGroup(), and name().

◆ findOneItem()

virtual ItemInternal * Arcane::IItemFamily::findOneItem ( Int64 unique_id)
pure virtual

Unique ID entity unique_id.

If no entity with this unique_id is found, returns nullptr.

Precondition
hasUniqueIdMap()

References findOneItem().

Referenced by findOneItem().

◆ findVariable()

virtual IVariable * Arcane::IItemFamily::findVariable ( const String & name,
bool throw_exception = false )
pure virtual

Searches for the variable name name associated with this family.

If no variable with the name name exists, and if throw_exception is false, returns 0; otherwise, it throws an exception.

References findVariable(), and name().

Referenced by findVariable(), and Arcane::Hdf5VariableReaderHelper::open().

◆ itemsNewOwner()

virtual VariableItemInt32 & Arcane::IItemFamily::itemsNewOwner ( )
pure virtual

Variable containing the number of the new subdomain owning the entity.

This variable is only used for mesh partitioning.

◆ itemSortFunction()

virtual IItemInternalSortFunction * Arcane::IItemFamily::itemSortFunction ( ) const
pure virtual

Entity sorting function.

The instance of this class remains the owner of the returned object, which must not be destroyed or modified.

See also
setItemSortFunction()

References itemSortFunction().

Referenced by itemSortFunction().

◆ itemsUniqueIdToLocalId() [1/2]

virtual void Arcane::IItemFamily::itemsUniqueIdToLocalId ( Int32ArrayView local_ids,
ConstArrayView< ItemUniqueId > unique_ids,
bool do_fatal = true ) const
pure virtual

Converts an array of unique numbers to local numbers.

This operation takes as input the unique_ids array containing the unique numbers of entities of type item_kind and returns in local_ids the corresponding local number for this subdomain.

The complexity of this operation depends on the implementation. The default implementation uses a hash table. The average complexity is therefore constant.

If do_fatal is true, a fatal error is generated if an entity is not found, otherwise the not found element has the value NULL_ITEM_ID.

References itemsUniqueIdToLocalId().

◆ itemsUniqueIdToLocalId() [2/2]

virtual void Arcane::IItemFamily::itemsUniqueIdToLocalId ( Int32ArrayView local_ids,
Int64ConstArrayView unique_ids,
bool do_fatal = true ) const
pure virtual

Converts an array of unique numbers to local numbers.

This operation takes as input the unique_ids array containing the unique numbers of entities of type item_kind and returns in local_ids the corresponding local number for this subdomain.

The complexity of this operation depends on the implementation. The default implementation uses a hash table. The average complexity is therefore constant.

If do_fatal is true, a fatal error is generated if an entity is not found, otherwise the not found element has the value NULL_ITEM_ID.

Precondition
hasUniqueIdMap()

References itemsUniqueIdToLocalId().

Referenced by Arcane::CartesianMeshCoarsening::createCoarseCells(), itemsUniqueIdToLocalId(), and itemsUniqueIdToLocalId().

◆ maxLocalId()

◆ parentFamily()

virtual IItemFamily * Arcane::IItemFamily::parentFamily ( ) const
pure virtual

IItemFamily parent.

Resulting from sub-mesh nesting

Returns
nullptr if there is no parent family

◆ partialEndUpdate()

virtual void Arcane::IItemFamily::partialEndUpdate ( )
pure virtual

Partial update.

Updates the internal structures after a family modification. This is an optimized version of endUpdate() when you want to perform multiple mesh modifications. This method DOES NOT update the groups or variables associated with this family. Only the allItems() group is available. It is possible to update a group via partialEndUpdateGroup() and a variable via partialEndUpdateVariable().

This method is reserved for experienced users. For others, it is better to use endUpdate().

References partialEndUpdate().

Referenced by partialEndUpdate().

◆ partialEndUpdateGroup()

virtual void Arcane::IItemFamily::partialEndUpdateGroup ( const ItemGroup & group)
pure virtual

Updates a group.

Updates the group after a family modification. The update consists of removing entities from the group that were possibly destroyed during the modification.

See also
partialEndUpdate().

References partialEndUpdateGroup().

Referenced by partialEndUpdateGroup().

◆ partialEndUpdateVariable()

virtual void Arcane::IItemFamily::partialEndUpdateVariable ( IVariable * variable)
pure virtual

Updates a variable.

Updates the variable after a family modification. The update consists of resizing the variable after a possible addition of entities.

See also
partialEndUpdate().

References partialEndUpdateVariable().

Referenced by partialEndUpdateVariable().

◆ reduceFromGhostItems() [1/2]

virtual void Arcane::IItemFamily::reduceFromGhostItems ( IVariable * v,
IDataOperation * operation )
pure virtual

Applies a reduction operation from ghost items.

This operation is the inverse of synchronization.

The sub-domain retrieves the values of variable v on the entities it shares with other sub-domains, and the reduction operation operation is applied to this variable.

References reduceFromGhostItems().

Referenced by reduceFromGhostItems(), and reduceFromGhostItems().

◆ reduceFromGhostItems() [2/2]

virtual void Arcane::IItemFamily::reduceFromGhostItems ( IVariable * v,
Parallel::eReduceType operation )
pure virtual

Applies a reduction operation from ghost items.

This operation is the inverse of synchronization.

The sub-domain retrieves the values of variable v on the entities it shares with other sub-domains, and the reduction operation operation is applied to this variable.

References reduceFromGhostItems().

◆ removeItems2()

virtual void Arcane::IItemFamily::removeItems2 ( mesh::ItemDataList & item_data_list)
pure virtual

Removes entities.

Uses the graph (Families, Connectivities) ItemFamilyNetwork

TODO: To be put in the internal API

◆ resizeVariables()

virtual void Arcane::IItemFamily::resizeVariables ( bool force_resize)
pure virtual

Resizes the variables of this family.

This method is internal to Arcane.

◆ setHasUniqueIdMap()

virtual void Arcane::IItemFamily::setHasUniqueIdMap ( bool v)
pure virtual

Indicates whether the family has a conversion table from uniqueId to localId.

The conversion table allows using the methods itemsUniqueIdToLocalId() or findOneItem().

This method can only be called when there are no entities in the family.

The node, edge, face, and cell families of the mesh must have a conversion table.

References setHasUniqueIdMap().

Referenced by setHasUniqueIdMap().

◆ setItemSortFunction()

virtual void Arcane::IItemFamily::setItemSortFunction ( IItemInternalSortFunction * sort_function)
pure virtual

Positions the entity sorting function.

The default method is to sort entities by ascending uniqueId(). If sort_function is null, the default method will be used. Otherwise, sort_function replaces the previous function, which is destroyed (via delete). Sorting is performed via the call to compactItems().

See also
itemSortFunction()

References setItemSortFunction().

Referenced by setItemSortFunction().

◆ synchronize() [1/2]

virtual void Arcane::IItemFamily::synchronize ( VariableCollection variables)
pure virtual

Synchronizes the variables variables.

The variables variables must all come from this family and must not be partial.

References synchronize().

Referenced by synchronize().

◆ synchronize() [2/2]

void Arcane::IItemFamily::synchronize ( VariableCollection variables,
Int32ConstArrayView local_ids )
virtual

Synchronizes the variables variables on a list of entities.

The variables variables must all come from this family and must not be partial.

Only the entities listed in local_ids will be synchronized. Note: an entity present in this list on one sub-domain must be present in this list for any other sub-domain that possesses this entity.

Definition at line 307 of file InterfaceImpl.cc.

References ARCANE_THROW.

◆ toDoFFamily()

virtual IDoFFamily * Arcane::IItemFamily::toDoFFamily ( )
inlinevirtual

Returns the interface of the particle family for this family.

The IParticleFamily interface only exists if this family is a particle family (itemKind()==IK_Particle). For other family kinds, 0 is returned.

Definition at line 622 of file IItemFamily.h.

References toDoFFamily().

Referenced by toDoFFamily().

◆ toParticleFamily()

virtual IParticleFamily * Arcane::IItemFamily::toParticleFamily ( )
pure virtual

Returns the interface of the particle family for this family.

The IParticleFamily interface only exists if this family is a particle family (itemKind()==IK_Particle). For other family kinds, 0 is returned.

References toParticleFamily().

Referenced by toParticleFamily().

◆ view()

virtual ItemVectorView Arcane::IItemFamily::view ( Int32ConstArrayView local_ids)
pure virtual

View on the entities.

Returns a view on the entities with local numbers local_ids.

Warning
This view is only valid as long as the family does not evolve. In particular, adding, removing, or compacting invalidates the view. If you want to keep a list even after modification, you must use groups (ItemGroup).

Referenced by Arcane::CartesianMeshCoarsening::createCoarseCells(), Arcane::Materials::ItemMaterialVariableArray< DataType >::serialize(), and Arcane::Materials::ItemMaterialVariableScalar< DataType >::serialize().


The documentation for this class was generated from the following files: