exodusII_io_helper.h

Go to the documentation of this file.

// The libMesh Finite Element Library.
// Copyright (C) 2002-2026 Benjamin S. Kirk, John W. Peterson, Roy H. Stogner

// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.

// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// Lesser General Public License for more details.

// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

#ifndef LIBMESH_EXODUSII_IO_HELPER_H
#define LIBMESH_EXODUSII_IO_HELPER_H

#include "libmesh/libmesh_config.h"

#ifdef LIBMESH_HAVE_EXODUS_API

// Local includes
#include "libmesh/parallel_object.h"
#include "libmesh/point.h"
#include "libmesh/boundary_info.h" // BoundaryInfo::BCTuple
#include "libmesh/enum_elem_type.h" // INVALID_ELEM
#include "libmesh/exodus_header_info.h"

// C++ includes
#include <iostream>
#include <string>
#include <vector>
#include <map>

// Macros to simplify checking Exodus error codes
#define EX_CHECK_ERR(code, msg)                 \
  do {                                          \
    if ((code) < 0) {                           \
      libmesh_error_msg((msg));                 \
    } } while (0)

#define EX_EXCEPTIONLESS_CHECK_ERR(code, msg)   \
  do {                                          \
    if ((code) < 0) {                           \
      libMesh::err << (msg) << std::endl;       \
      libmesh_exceptionless_error();            \
    } } while (0)

// Before we include a header wrapped in a namespace, we'd better make
// sure none of its dependencies end up in that namespace
#include <errno.h>
#include <stddef.h>
#include <stdlib.h>
#include <stdint.h>

namespace libMesh
{

// Forward declarations
class MeshBase;
class DofObject;

class ExodusII_IO_Helper : public ParallelObject
{
public:
  ExodusII_IO_Helper(const ParallelObject & parent,
                     bool v=false,
                     bool run_only_on_proc0=true,
                     bool single_precision=false);
  ExodusII_IO_Helper (const ExodusII_IO_Helper &) = default;
  ExodusII_IO_Helper (ExodusII_IO_Helper &&) = default;
  virtual ~ExodusII_IO_Helper();

  ExodusII_IO_Helper & operator= (const ExodusII_IO_Helper &) = delete;
  ExodusII_IO_Helper & operator= (ExodusII_IO_Helper &&) = delete;

  static int get_exodus_version();

  const char * get_elem_type() const;

  void set_add_sides(bool add_sides);

  bool get_add_sides();

  void open(const char * filename, bool read_only);

  ExodusHeaderInfo read_header() const;

  void read_and_store_header_info();

  void read_qa_records();

  void print_header();

  void read_nodes();

  void read_node_num_map();

  void read_bex_cv_blocks();

  void print_nodes(std::ostream & out_stream = libMesh::out);

  void read_block_info();

  int get_block_id(int index);

  std::string get_block_name(int index);

  int get_side_set_id(int index);

  std::string get_side_set_name(int index);

  int get_node_set_id(int index);

  std::string get_node_set_name(int index);

  void read_elem_in_block(int block);

  void read_edge_blocks(MeshBase & mesh);

  void read_elem_num_map();

  void read_sideset_info();

  void read_nodeset_info();

  void read_elemset_info();

  void read_sideset(int id, int offset);

  void read_elemset(int id, int offset);

  void read_all_nodesets();

  void close() noexcept;

  void read_time_steps();

  void read_num_time_steps();

  void read_nodal_var_values(std::string nodal_var_name, int time_step);

  void read_elemental_var_values(std::string elemental_var_name,
                                 int time_step,
                                 std::map<dof_id_type, Real> & elem_var_value_map);

  dof_id_type get_libmesh_node_id(int exodus_node_id);
  dof_id_type get_libmesh_elem_id(int exodus_elem_id);

  void conditionally_set_node_unique_id(
    MeshBase & mesh, Node * node, int zero_based_node_num_map_index);
  void conditionally_set_elem_unique_id(
    MeshBase & mesh, Elem * elem, int zero_based_elem_num_map_index);

private:

  dof_id_type get_libmesh_id(
    int exodus_id,
    const std::vector<int> & num_map);

  void set_dof_object_unique_id(
    MeshBase & mesh,
    DofObject * dof_object,
    int exodus_mapped_id);

public:

  virtual void create(std::string filename);

  virtual void initialize(std::string title, const MeshBase & mesh, bool use_discontinuous=false);

  virtual void write_nodal_coordinates(const MeshBase & mesh, bool use_discontinuous=false);

  virtual void write_elements(const MeshBase & mesh,
                              bool use_discontinuous=false);

  virtual void write_sidesets(const MeshBase & mesh);

  virtual void write_nodesets(const MeshBase & mesh);

  virtual void initialize_element_variables(std::vector<std::string> names,
                                            const std::vector<std::set<subdomain_id_type>> & vars_active_subdomains);

  void initialize_nodal_variables(std::vector<std::string> names);

  void initialize_global_variables(std::vector<std::string> names);

  void write_timestep(int timestep, Real time);

  void write_elemsets(const MeshBase & mesh);

  void
  write_sideset_data (const MeshBase & mesh,
                      int timestep,
                      const std::vector<std::string> & var_names,
                      const std::vector<std::set<boundary_id_type>> & side_ids,
                      const std::vector<std::map<BoundaryInfo::BCTuple, Real>> & bc_vals);

  void
  read_sideset_data (const MeshBase & mesh,
                     int timestep,
                     std::vector<std::string> & var_names,
                     std::vector<std::set<boundary_id_type>> & side_ids,
                     std::vector<std::map<BoundaryInfo::BCTuple, Real>> & bc_vals);

  void
  get_sideset_data_indices (const MeshBase & mesh,
                            std::map<BoundaryInfo::BCTuple, unsigned int> & bc_array_indices);

  void
  write_nodeset_data (int timestep,
                      const std::vector<std::string> & var_names,
                      const std::vector<std::set<boundary_id_type>> & node_boundary_ids,
                      const std::vector<std::map<BoundaryInfo::NodeBCTuple, Real>> & bc_vals);

  void
  read_nodeset_data (int timestep,
                     std::vector<std::string> & var_names,
                     std::vector<std::set<boundary_id_type>> & node_boundary_ids,
                     std::vector<std::map<BoundaryInfo::NodeBCTuple, Real>> & bc_vals);

  void
  get_nodeset_data_indices (std::map<BoundaryInfo::NodeBCTuple, unsigned int> & bc_array_indices);

  void
  write_elemset_data (int timestep,
                      const std::vector<std::string> & var_names,
                      const std::vector<std::set<elemset_id_type>> & elemset_ids_in,
                      const std::vector<std::map<std::pair<dof_id_type, elemset_id_type>, Real>> & elemset_vals);

  void
  read_elemset_data (int timestep,
                     std::vector<std::string> & var_names,
                     std::vector<std::set<elemset_id_type>> & elemset_ids_in,
                     std::vector<std::map<std::pair<dof_id_type, elemset_id_type>, Real>> & elemset_vals);

  void
  get_elemset_data_indices (std::map<std::pair<dof_id_type, elemset_id_type>, unsigned int> & elemset_array_indices);

  void write_element_values
  (const MeshBase & mesh,
   const std::vector<Real> & values,
   int timestep,
   const std::vector<std::set<subdomain_id_type>> & vars_active_subdomains);

  void write_element_values_element_major
  (const MeshBase & mesh,
   const std::vector<Real> & values,
   int timestep,
   const std::vector<std::set<subdomain_id_type>> & vars_active_subdomains,
   const std::vector<std::string> & derived_var_names,
   const std::map<subdomain_id_type, std::vector<std::string>> & subdomain_to_var_names);

  void write_nodal_values(int var_id, const std::vector<Real> & values, int timestep);

  void write_information_records(const std::vector<std::string> & records);

  void write_global_values(const std::vector<Real> & values, int timestep);

  void update();

  void read_global_values(std::vector<Real> & values, int timestep);

  void use_mesh_dimension_instead_of_spatial_dimension(bool val);

  void set_hdf5_writing(bool write_hdf5);

  void write_as_dimension(unsigned dim);

  void set_coordinate_offset(Point p);

  void set_max_name_length(unsigned int max_length);

  std::vector<std::string>
  get_complex_names(const std::vector<std::string> & names,
                    bool write_complex_abs) const;

  std::vector<std::set<subdomain_id_type>>
  get_complex_vars_active_subdomains
  (const std::vector<std::set<subdomain_id_type>> & vars_active_subdomains,
   bool write_complex_abs) const;

  std::map<subdomain_id_type, std::vector<std::string>>
  get_complex_subdomain_to_var_names
  (const std::map<subdomain_id_type, std::vector<std::string>> & subdomain_to_var_names,
   bool write_complex_abs) const;

  class Conversion;

  class NamesData;

  void message(std::string_view msg);

  void message(std::string_view msg, int i);

  // File identification flag
  int ex_id;

  // General error flag
  int ex_err;

  // struct which contains data fields from the Exodus file header
  ExodusHeaderInfo header_info;

  // Problem title (Use vector<char> to emulate a char *)
  std::vector<char> & title;

  // Number of dimensions in the mesh
  int & num_dim;

  // Total number of nodes in the mesh
  int & num_nodes;

  // Total number of elements in the mesh
  int & num_elem;

  // Smallest element id which exceeds every element id in the mesh.
  // (this may exceed num_elem due to mapping)
  int end_elem_id() const;

  // Total number of element blocks
  int & num_elem_blk;

  // Total number of edges
  int & num_edge;

  // Total number of edge blocks. The sum of the number of edges in
  // each block must equal num_edge.
  int & num_edge_blk;

  // Total number of node sets
  int & num_node_sets;

  // Total number of side sets
  int & num_side_sets;

  // Total number of element sets
  int & num_elem_sets;

  // Number of global variables
  int num_global_vars;

  // Number of sideset variables
  int num_sideset_vars;

  // Number of nodeset variables
  int num_nodeset_vars;

  // Number of elemset variables
  int num_elemset_vars;

  // Number of elements in this block
  int num_elem_this_blk;

  // Number of nodes in each element
  int num_nodes_per_elem;

  // Number of attributes for a given block
  int num_attr;

  // Total number of elements in all side sets
  int num_elem_all_sidesets;

  // Total number of elements in all elem sets
  int num_elem_all_elemsets;

  // Vector of element block identification numbers
  std::vector<int> block_ids;

  // Vector of edge block identification numbers
  std::vector<int> edge_block_ids;

  // Vector of nodes in an element
  std::vector<int> connect;

  // Vector of the sideset IDs
  std::vector<int> ss_ids;

  // Vector of the nodeset IDs
  std::vector<int> nodeset_ids;

  // Vector of the elemset IDs
  std::vector<int> elemset_ids;

  // Number of sides in each sideset
  std::vector<int> num_sides_per_set;

  // Number of nodes in each nodeset
  std::vector<int> num_nodes_per_set;

  // Number of elems in each elemset
  std::vector<int> num_elems_per_set;

  // Number of distribution factors per sideset
  std::vector<int> num_df_per_set;

  // Number of distribution factors per nodeset
  std::vector<int> num_node_df_per_set;

  // Number of distribution factors per elemset
  std::vector<int> num_elem_df_per_set;

  // Starting indices for each nodeset in the node_sets_node_list vector.
  // Used in the calls to ex_{put,get}_concat_node_sets().
  std::vector<int> node_sets_node_index;

  // Starting indices for each nodeset in the node_sets_dist_fact vector.
  // Used in the calls to ex_{put,get}_concat_node_sets().
  std::vector<int> node_sets_dist_index;

  // Node ids for all nodes in nodesets, concatenated together.
  // Used in the calls to ex_{put,get}_concat_node_sets().
  std::vector<int> node_sets_node_list;

  // Distribution factors for all nodes in all nodesets, concatenated together.
  // Used in the calls to ex_{put,get}_concat_node_sets().
  std::vector<Real> node_sets_dist_fact;

  // List of element numbers in all sidesets
  std::vector<int> elem_list;

  // Side (face/edge) number actually on the boundary
  std::vector<int> side_list;

  // Side (face/edge) id number
  std::vector<int> id_list;

  // List of element numbers in all elemsets
  std::vector<int> elemset_list;

  // List of elemset ids for all elements in elemsets
  std::vector<int> elemset_id_list;

  // Optional mapping from internal [0,num_nodes) to arbitrary indices
  std::vector<int> node_num_map;

  // Optional mapping from internal [0,num_elem) to arbitrary indices
  std::vector<int> elem_num_map;

  // x locations of node points
  std::vector<Real> x;

  // y locations of node points
  std::vector<Real> y;

  // z locations of node points
  std::vector<Real> z;

  // Spline weights associated with node points, in IGA meshes
  std::vector<Real> w;

  // Number of Bezier Extraction coefficient vectors in a block
  unsigned int bex_num_elem_cvs;

  // Bezier Extraction connectivity indices, in IGA meshes
  std::vector<std::vector<long unsigned int>> bex_cv_conn;

  // Bezier Extraction coefficient vectors, in IGA meshes
  // bex_dense_constraint_vecs[block_num][vec_num][column_num] = coef
  std::vector<std::vector<std::vector<Real>>> bex_dense_constraint_vecs;

  // Type of element in a given block
  std::vector<char> elem_type;

  // Maps libMesh element numbers to Exodus element numbers
  // gets filled in when write_elements gets called
  std::map<dof_id_type, dof_id_type> libmesh_elem_num_to_exodus;
  std::vector<int> exodus_elem_num_to_libmesh;

  // Map of all node numbers connected to local node numbers to their exodus numbering.
  // The exodus numbers are stored in here starting with 1
  std::map<dof_id_type, dof_id_type> libmesh_node_num_to_exodus;
  std::vector<int> exodus_node_num_to_libmesh;

  // The number of timesteps in the file, as returned by ex_inquire
  int num_time_steps;

  // The timesteps stored in the solution file, filled by read_time_steps()
  std::vector<Real> time_steps;

  // The number of nodal variables in the Exodus file
  int num_nodal_vars;

  // The names of the nodal variables stored in the Exodus file
  std::vector<std::string> nodal_var_names;

  // Holds the nodal variable values for a given variable, one value
  // per node, indexed by libMesh node id.
  // This is a map so it can handle Nemesis files as well.
  std::map<dof_id_type, Real> nodal_var_values;

  // The number of elemental variables in the Exodus file
  int num_elem_vars;

  // The names of the elemental variables stored in the Exodus file
  std::vector<std::string> elem_var_names;

  // Holds the elemental variable values for a given variable, one value per element
  std::vector<Real> elem_var_values;

  // The names of the global variables stored in the Exodus file
  std::vector<std::string> global_var_names;

  // The names of the sideset variables stored in the Exodus file
  std::vector<std::string> sideset_var_names;

  // The names of the nodeset variables stored in the Exodus file
  std::vector<std::string> nodeset_var_names;

  // The names of the elemset variables stored in the Exodus file
  std::vector<std::string> elemset_var_names;

  // Maps of Ids to named entities
  std::map<int, std::string> id_to_block_names;
  std::map<int, std::string> id_to_edge_block_names;
  std::map<int, std::string> id_to_ss_names;
  std::map<int, std::string> id_to_ns_names;
  std::map<int, std::string> id_to_elemset_names;

  // On/Off message flag
  bool verbose;

  // Same as the ExodusII_IO flag by the same name. This flag is
  // also set whenever ExodusII_IO::set_unique_ids_from_maps() is called.
  bool set_unique_ids_from_maps;

  // This flag gets set after the Exodus file has been successfully opened for writing.
  // Both the create() and open() (if called with EX_WRITE) functions may set this flag.
  bool opened_for_writing;

  // This flag gets set after the open() function has been successfully called.
  // We call open() to open an ExodusII file for reading.
  bool opened_for_reading;

  // When either create() or open() is called, the Helper stores the
  // name of the opened file as current_filename.  This way, the
  // ExodusII_IO object can check to see if, on subsequent writes, the
  // user is asking to write to a *different* filename from the one
  // that is currently open, and signal an error.  The current
  // ExodusII_IO implementation is designed to work with a single file
  // only, so if you want to write to multiple Exodus files, use a
  // different ExodusII_IO object for each one.
  std::string current_filename;

  enum ExodusVarType {NODAL=0, ELEMENTAL=1, GLOBAL=2, SIDESET=3, NODESET=4, ELEMSET=5};
  void read_var_names(ExodusVarType type);

  const ExodusII_IO_Helper::Conversion &
  get_conversion(const ElemType type) const;

  const ExodusII_IO_Helper::Conversion &
  get_conversion(std::string type_str) const;

  /*
   * Returns the sum of node "offsets" that are to be expected from a
   * parallel nodal solution vector that has had "fake" nodes added on
   * each processor.  This plus a node id gives a valid nodal solution
   * vector index.
   */
  dof_id_type node_id_to_vec_id(dof_id_type n) const
  {
    if (_added_side_node_offsets.empty())
      return n;

    // Find the processor id that has node_id in the parallel vec
    const auto lb = std::upper_bound(_true_node_offsets.begin(),
                                     _true_node_offsets.end(), n);
    libmesh_assert(lb != _true_node_offsets.end());
    const processor_id_type p = lb - _true_node_offsets.begin();

    return n + (p ? _added_side_node_offsets[p-1] : 0);
  }

  /*
   * Returns the sum of both added node "offsets" on processors 0
   * through p-1 and real nodes added on processors 0 to p.
   * This is the starting index for added nodes' data.
   */
  dof_id_type added_node_offset_on(processor_id_type p) const
  {
    libmesh_assert (p < _true_node_offsets.size());
    const dof_id_type added_node_offsets =
      (_added_side_node_offsets.empty() || !p) ? 0 :
      _added_side_node_offsets[p-1];
    return _true_node_offsets[p] + added_node_offsets;
  }


protected:
  void check_existing_vars(ExodusVarType type, std::vector<std::string> & names, std::vector<std::string> & names_from_file);

  void write_var_names(ExodusVarType type, const std::vector<std::string> & names);

  // If true, whenever there is an I/O operation, only perform if if we are on processor 0.
  bool _run_only_on_proc0;

  // This flag gets set after the create() function has been successfully called.
  bool _opened_by_create;

  // True once the elem vars are initialized
  bool _elem_vars_initialized;

  // True once the global vars are initialized
  bool _global_vars_initialized;

  // True once the nodal vars are initialized
  bool _nodal_vars_initialized;

  // If true, use the Mesh's dimension (as determined by the dimension
  // of the elements comprising the mesh) instead of the mesh's
  // spatial dimension, when writing.  By default this is false.
  bool _use_mesh_dimension_instead_of_spatial_dimension;

  // If true, write an HDF5 file when available.  If false, write the
  // old format.
  bool _write_hdf5;

  // The maximum name length to use when writing
  unsigned int _max_name_length;

  // Set once the elem num map has been read
  int _end_elem_id;

  // Use this for num_dim when writing the Exodus file.  If non-zero, supersedes
  // any value set in _use_mesh_dimension_instead_of_spatial_dimension.
  unsigned _write_as_dimension;

  // On output, shift every point by _coordinate_offset
  Point _coordinate_offset;

  // If true, forces single precision I/O
  bool _single_precision;

  std::vector<dof_id_type> _added_side_node_offsets;

  std::vector<dof_id_type> _true_node_offsets;

  struct MappedOutputVector
  {
    // If necessary, allocates space to store a version of vec_in in a
    // different precision than it was input with.
    MappedOutputVector(const std::vector<Real> & vec_in,
                       bool single_precision_in);

    ~MappedOutputVector() = default;

    // Returns void * pointer to either the mapped data or the
    // original data, as necessary.
    void * data();

  private:
    const std::vector<Real> & our_data;
    bool single_precision;
    std::vector<double> double_vec;
    std::vector<float> float_vec;
  };

  struct MappedInputVector
  {
    MappedInputVector(std::vector<Real> & vec_in,
                      bool single_precision_in);
    ~MappedInputVector();

    // Returns void * pointer to either the mapped data or the
    // original data, as necessary.
    void * data();

  private:
    std::vector<Real> & our_data;
    bool single_precision;
    std::vector<double> double_vec;
    std::vector<float> float_vec;
  };


protected:

  virtual void read_var_names_impl(const char * var_type,
                                   int & count,
                                   std::vector<std::string> & result);

private:

  bool _add_sides = false;

  void write_var_names_impl(const char * var_type,
                            int & count,
                            const std::vector<std::string> & names);

  std::map<std::string, ElemType> element_equivalence_map;
  void init_element_equivalence_map();

  std::map<int, std::map<ElemType, ExodusII_IO_Helper::Conversion>> conversion_map;
  void init_conversion_map();
};



class ExodusII_IO_Helper::Conversion
{
public:

  Conversion()
    : node_map(nullptr),
      inverse_node_map(nullptr),
      side_map(nullptr),
      inverse_side_map(nullptr),
      shellface_map(nullptr),
      inverse_shellface_map(nullptr),
      shellface_index_offset(0),
      libmesh_type(INVALID_ELEM),
      dim(0),
      n_nodes(0),
      exodus_type("")
  {}

  int get_node_map(int i) const;

  int get_inverse_node_map(int i) const;

  int get_side_map(int i) const;

  int get_inverse_side_map(int i) const;

  int get_shellface_map(int i) const;

  int get_inverse_shellface_map(int i) const;

  ElemType libmesh_elem_type() const;

  std::string exodus_elem_type() const;

  std::size_t get_shellface_index_offset() const;

  static const int invalid_id;

  const std::vector<int> * node_map;

  const std::vector<int> * inverse_node_map;

  const std::vector<int> * side_map;

  const std::vector<int> * inverse_side_map;

  const std::vector<int> * shellface_map;

  const std::vector<int> * inverse_shellface_map;

  size_t shellface_index_offset;

  ElemType libmesh_type;

  int dim;

  int n_nodes;

  std::string exodus_type;
};



class ExodusII_IO_Helper::NamesData
{
public:
  explicit
  NamesData(size_t n_strings, size_t string_length);

  void push_back_entry(const std::string & name);

  char ** get_char_star_star();

  char * get_char_star(int i);

private:
  // C++ data structures for managing string memory
  std::vector<std::vector<char>> data_table;
  std::vector<char *> data_table_pointers;

  size_t counter;
  size_t table_size;
};


inline void ExodusII_IO_Helper::set_add_sides(bool add_sides)
{
  _add_sides = add_sides;
}


inline bool ExodusII_IO_Helper::get_add_sides()
{
  return _add_sides;
}


inline int ExodusII_IO_Helper::end_elem_id() const
{
  libmesh_assert_equal_to(std::size_t(num_elem), elem_num_map.size());
  return _end_elem_id;
}


} // namespace libMesh

#endif // LIBMESH_HAVE_EXODUS_API

#endif // LIBMESH_EXODUSII_IO_HELPER_H