Shuenhoy/vtk-m
1
0
Fork 0
mirror of https://gitlab.kitware.com/vtk/vtk-m synced 2024-09-08 13:23:51 +00:00
Code Issues 2 Actions Packages Projects Releases Wiki Activity

Clarify field index ordering in Doxygen

Browse Source 
The fields in a `DataSet` are indexed from `0` to `GetNumberOfFields() - 1`.
It is natural to assume that the fields will be indexed in the order that
they are added, but they are not. Rather, the indexing is arbitrary and can
change any time a field is added to the dataset.

To make this more clear, Doxygen documentation is added to the `DataSet`
methods to inform users to not make any assumptions about the order of
field indexing.
This commit is contained in:
Kenneth Moreland 2023-01-09 10:26:57 -07:00
parent a15ea70ec7
commit c0e0032e1d
2 changed files with 121 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/changelog/document-field-index-order.md Normal file
View File

@ -0,0 +1,10 @@
# Clarify field index ordering in Doxygen
The fields in a `DataSet` are indexed from `0` to `GetNumberOfFields() - 1`.
It is natural to assume that the fields will be indexed in the order that
they are added, but they are not. Rather, the indexing is arbitrary and can
change any time a field is added to the dataset.
To make this more clear, Doxygen documentation is added to the `DataSet`
methods to inform users to not make any assumptions about the order of
field indexing.

168
vtkm/cont/DataSet.h
View File

@ -46,22 +46,37 @@ public:
VTKM_CONT void Clear();
/// Get the number of cells contained in this DataSet
/// \brief Get the number of cells contained in this DataSet
VTKM_CONT vtkm::Id GetNumberOfCells() const;
/// Get the number of points contained in this DataSet
/// \brief Get the number of points contained in this DataSet
///
/// Note: All coordinate systems for a DataSet are expected
/// to have the same number of points.
VTKM_CONT vtkm::Id GetNumberOfPoints() const;
/// \brief Adds a field to the `DataSet`.
///
/// Note that the indexing of fields is not the same as the order in which they are
/// added, and that adding a field can arbitrarily reorder the integer indexing of
/// all the fields. To retrieve a specific field, retrieve the field by name, not by
/// integer index.
VTKM_CONT void AddField(const Field& field);
///@{
/// \brief Retrieves a field by index.
///
/// Note that the indexing of fields is not the same as the order in which they are
/// added, and that adding a field can arbitrarily reorder the integer indexing of
/// all the fields. To retrieve a specific field, retrieve the field by name, not by
/// integer index. This method is most useful for iterating over all the fields of
/// a `DataSet` (indexed from `0` to `NumberOfFields() - 1`).
VTKM_CONT
const vtkm::cont::Field& GetField(vtkm::Id index) const { return this->Fields.GetField(index); }
VTKM_CONT
vtkm::cont::Field& GetField(vtkm::Id index) { return this->Fields.GetField(index); }
///@}
VTKM_CONT
bool HasField(const std::string& name,
@ -89,8 +104,14 @@ public:
}
/// Returns the field that matches the provided name and association
/// Will return -1 if no match is found
/// \brief Returns the field that matches the provided name and association.
///
/// This method will return -1 if no match for the field is found.
///
/// Note that the indexing of fields is not the same as the order in which they are
/// added, and that adding a field can arbitrarily reorder the integer indexing of
/// all the fields. To retrieve a specific field, retrieve the field by name, not by
/// integer index.
VTKM_CONT
vtkm::Id GetFieldIndex(
const std::string& name,
@ -99,8 +120,10 @@ public:
return this->Fields.GetFieldIndex(name, assoc);
}
/// Returns the field that matches the provided name and association
/// Will throw an exception if no match is found
/// \brief Returns the field that matches the provided name and association.
///
/// This method will throw an exception if no match is found. Use `HasField()` to query
/// whether a particular field exists.
///@{
VTKM_CONT
const vtkm::cont::Field& GetField(
@ -120,8 +143,10 @@ public:
}
///@}
/// Returns the first cell field that matches the provided name.
/// Will throw an exception if no match is found
/// \brief Returns the first cell field that matches the provided name.
///
/// This method will throw an exception if no match is found. Use `HasCellField()` to query
/// whether a particular field exists.
///@{
VTKM_CONT
const vtkm::cont::Field& GetCellField(const std::string& name) const
@ -136,15 +161,19 @@ public:
}
///@}
/// Returns the cell field that matches the ghost cell field name.
/// Will throw an exception if no match is found
/// \brief Returns the cell field that matches the ghost cell field name.
///
/// This method will throw an exception if no match is found. Use `HasGhostCellField()` to query
/// whether a particular field exists.
///@{
VTKM_CONT
const vtkm::cont::Field& GetGhostCellField() const;
///@}
/// Returns the first point field that matches the provided name.
/// Will throw an exception if no match is found
/// \brief Returns the first point field that matches the provided name.
///
/// This method will throw an exception if no match is found. Use `HasPointField()` to query
/// whether a particular field exists.
///@{
VTKM_CONT
const vtkm::cont::Field& GetPointField(const std::string& name) const
@ -159,6 +188,13 @@ public:
}
///@}
///@{
/// \brief Adds a point field of a given name to the `DataSet`.
///
/// Note that the indexing of fields is not the same as the order in which they are
/// added, and that adding a field can arbitrarily reorder the integer indexing of
/// all the fields. To retrieve a specific field, retrieve the field by name, not by
/// integer index.
VTKM_CONT
void AddPointField(const std::string& fieldName, const vtkm::cont::UnknownArrayHandle& field)
{
@ -185,58 +221,21 @@ public:
this->AddField(
make_Field(fieldName, vtkm::cont::Field::Association::Points, field, n, vtkm::CopyFlag::On));
}
///@}
//Cell centered field
///@{
/// \brief Adds a cell field of a given name to the `DataSet`.
///
/// Note that the indexing of fields is not the same as the order in which they are
/// added, and that adding a field can arbitrarily reorder the integer indexing of
/// all the fields. To retrieve a specific field, retrieve the field by name, not by
/// integer index.
VTKM_CONT
void AddCellField(const std::string& fieldName, const vtkm::cont::UnknownArrayHandle& field)
{
this->AddField(make_FieldCell(fieldName, field));
}
/// \brief Sets the name of the field to use for cell ghost levels.
///
/// This value can be set regardless of whether such a cell field actually exists.
VTKM_CONT void SetGhostCellFieldName(const std::string& name);
/// \brief Sets the cell field of the given name as the cell ghost levels.
///
/// If a cell field of the given name does not exist, an exception is thrown.
VTKM_CONT void SetGhostCellField(const std::string& name);
///@{
/// \brief Sets the ghost cell levels.
///
/// A field of the given name is added to the `DataSet`, and that field is set as the cell
/// ghost levels.
VTKM_CONT void SetGhostCellField(const vtkm::cont::Field& field);
VTKM_CONT void SetGhostCellField(const std::string& fieldName,
const vtkm::cont::UnknownArrayHandle& field);
///@}
/// \brief Sets the ghost cell levels to the given array.
///
/// A field with the global ghost cell field name (see `GlobalGhostCellFieldName`) is added
/// to the `DataSet` and made to be the cell ghost levels.
VTKM_CONT void SetGhostCellField(const vtkm::cont::UnknownArrayHandle& field);
VTKM_DEPRECATED(2.0, "Use SetGhostCellField.")
VTKM_CONT
void AddGhostCellField(const std::string& fieldName, const vtkm::cont::UnknownArrayHandle& field)
{
this->SetGhostCellField(fieldName, field);
}
VTKM_DEPRECATED(2.0, "Use SetGhostCellField.")
VTKM_CONT
void AddGhostCellField(const vtkm::cont::UnknownArrayHandle& field)
{
this->SetGhostCellField(field);
}
VTKM_DEPRECATED(2.0, "Use SetGhostCellField.")
VTKM_CONT
void AddGhostCellField(const vtkm::cont::Field& field) { this->SetGhostCellField(field); }
template <typename T, typename Storage>
VTKM_CONT void AddCellField(const std::string& fieldName,
const vtkm::cont::ArrayHandle<T, Storage>& field)
@ -257,6 +256,61 @@ public:
this->AddField(
make_Field(fieldName, vtkm::cont::Field::Association::Cells, field, n, vtkm::CopyFlag::On));
}
///@}
/// \brief Sets the name of the field to use for cell ghost levels.
///
/// This value can be set regardless of whether such a cell field actually exists.
VTKM_CONT void SetGhostCellFieldName(const std::string& name);
/// \brief Sets the cell field of the given name as the cell ghost levels.
///
/// If a cell field of the given name does not exist, an exception is thrown.
VTKM_CONT void SetGhostCellField(const std::string& name);
///@{
/// \brief Sets the ghost cell levels.
///
/// A field of the given name is added to the `DataSet`, and that field is set as the cell
/// ghost levels.
///
/// Note that the indexing of fields is not the same as the order in which they are
/// added, and that adding a field can arbitrarily reorder the integer indexing of
/// all the fields. To retrieve a specific field, retrieve the field by name, not by
/// integer index.
VTKM_CONT void SetGhostCellField(const vtkm::cont::Field& field);
VTKM_CONT void SetGhostCellField(const std::string& fieldName,
const vtkm::cont::UnknownArrayHandle& field);
///@}
/// \brief Sets the ghost cell levels to the given array.
///
/// A field with the global ghost cell field name (see `GlobalGhostCellFieldName`) is added
/// to the `DataSet` and made to be the cell ghost levels.
///
/// Note that the indexing of fields is not the same as the order in which they are
/// added, and that adding a field can arbitrarily reorder the integer indexing of
/// all the fields. To retrieve a specific field, retrieve the field by name, not by
/// integer index.
VTKM_CONT void SetGhostCellField(const vtkm::cont::UnknownArrayHandle& field);
VTKM_DEPRECATED(2.0, "Use SetGhostCellField.")
VTKM_CONT
void AddGhostCellField(const std::string& fieldName, const vtkm::cont::UnknownArrayHandle& field)
{
this->SetGhostCellField(fieldName, field);
}
VTKM_DEPRECATED(2.0, "Use SetGhostCellField.")
VTKM_CONT
void AddGhostCellField(const vtkm::cont::UnknownArrayHandle& field)
{
this->SetGhostCellField(field);
}
VTKM_DEPRECATED(2.0, "Use SetGhostCellField.")
VTKM_CONT
void AddGhostCellField(const vtkm::cont::Field& field) { this->SetGhostCellField(field); }
/// \brief Adds the given `CoordinateSystem` to the `DataSet`.