WriteUtilIface.hpp

Go to the documentation of this file.

/**
 * MOAB, a Mesh-Oriented datABase, is a software component for creating,
 * storing and accessing finite element mesh data.
 *
 * Copyright 2004 Sandia Corporation.  Under the terms of Contract
 * DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government
 * retains certain rights in this software.
 *
 * 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.
 *
 */

#ifndef MOAB_WRITE_UTIL_IFACE_HPP
#define MOAB_WRITE_UTIL_IFACE_HPP

#include "moab/Range.hpp"
#include "moab/Compiler.hpp"
#include <vector>

namespace moab
{

//! Interface implemented in MOAB which provides memory for mesh reading utilities
class WriteUtilIface
{
  public:
    //! Constructor
    WriteUtilIface() {}

    //! Destructor
    virtual ~WriteUtilIface() {}

    //! Check if the specified file already exists.
    //! Returns MB_SUCCESS if file does not exist, MB_ALREADY_ALLOCATED
    //! if file does exist, or MB_FAILURE for some other error condition.
    virtual ErrorCode check_doesnt_exist( const char* file_name ) = 0;

    //! Gather all entities in the mesh, or in the sets specified
    virtual ErrorCode gather_entities(
        Range& all_ents,                     /**< range in which entities are returned */
        const EntityHandle* ent_sets = NULL, /**< entity sets whose contents are to be gathered */
        int num_sets                 = 0 /**< number of sets in list */ ) = 0;

    //! Given information about the nodes to be written, and pointers to memory
    //! to which coordinates will be written, writes coordinate data there, and
    //! also assigns global ids to nodes & writes to a tag, if a tag is specified
    //! \param num_arrays Number of coordinate arrays requested
    //! \param num_nodes Number of nodes to be written
    //! \param entities Range of nodes to be written
    //! \param node_id_tag Tag used to write ids to nodes
    //! \param start_node_id Starting value for node ids
    //! \param arrays Pointers to memory where coordinate data will be written
    //! \return status Return status
    virtual ErrorCode get_node_coords( const int num_arrays,
                                       const int num_nodes,
                                       const Range& entities,
                                       Tag node_id_tag,
                                       const int start_node_id,
                                       std::vector< double* >& arrays ) = 0;

    /** Get array of coordinate values for nodes
     *
     * Given a range of node handles, retrieve a single or multiple coordinate
     * value(s) for each.
     *
     * Failure conditions:
     *  - invalid entity handles (not vertices, non-existent entity, etc.)
     *  - range is empty (<code>iter == end</code>)
     *  - <code>output_array</code> is null
     *  - insufficient space in <code>output_array</code>
     *
     *\param which_array  The coordinate to retrieve (0-&gt;X, 1-&gt;Y, 2-&gt;Z, -1-&gt;all)
     *\param begin        The first node handle.
     *\param end          One past the last node handle.
     *\param output_size  The size of <code>output_array</code>.
     *\param output_array The memory in which to write the node coordinates.
     *\author Jason Kraftcheck
     */
    virtual ErrorCode get_node_coords( const int which_array,
                                       Range::const_iterator begin,
                                       const Range::const_iterator& end,
                                       const size_t output_size,
                                       double* const output_array ) = 0;

    //! Given information about elements to be written and a pointer to memory
    //! where connectivity for those elements should be written, writes connectivity
    //! to that memory; uses node ids stored in a tag during call to <em>get_node_coords</em>
    //! function
    //! \param num_elements Number of elements to be written
    //! \param verts_per_element Number of vertices per element
    //! \param node_id_tag Tag used to store node ids
    //! \param entities Range of elements to be written
    //! \param element_id_tag Tag which should be used to store element ids
    //! \param start_element_id Starting value for element ids
    //! \param array Pointer to memory where connectivity data will be written
    //! \return status Return status
    virtual ErrorCode get_element_connect( const int num_elements,
                                           const int verts_per_element,
                                           Tag node_id_tag,
                                           const Range& entities,
                                           Tag element_id_tag,
                                           int start_element_id,
                                           int* array,
                                           bool add_sizes = false ) = 0;

    /** Get connectivity for elements
     *
     * Get the connectivity list for a range of elements.
     *
     * Failure cases:
     *  - Passed range is empty (<code>begin == end</code>).
     *  - <code>vertices_per_elem</code> is less than one
     *  - <code>element_array</code> is null.
     *  - The range contains invalid handles (non-existent entities,
     *      not an element, etc.)
     *  - Retrieving ID tag for an entity failed.
     *  - Insufficient space in passed array.
     *
     *\param begin        The first element handle
     *\param end          One past the last element handle
     *\param vertices_per_elem Number of vertices to retrieve for each
     *                    element. If the element has more vertices, the
     *                    element connectivity will be truncated. If
     *                    <code>vertices_per_elem</code> is greater than the
     *                    number of nodes for an element, the data will be
     *                    padded with zeros.
     *\param node_id_tag  A tag with integer values.
     *\param array_size   The length of <code>element_array</code>
     *\param element_array The memory location at which to store the
     *                    connectivity list.
     *\param add_sizes If true, writes size of connect array before connectivity in array
     *\author Jason Kraftcheck
     */
    virtual ErrorCode get_element_connect( Range::const_iterator begin,
                                           const Range::const_iterator& end,
                                           const int vertices_per_elem,
                                           Tag node_id_tag,
                                           const size_t array_size,
                                           int* const element_array,
                                           bool add_sizes = false ) = 0;

    /** Get connectivity for elements
     *
     * Get the connectivity list for a range of elements.
     *
     * Failure cases:
     *  - Passed range is empty (<code>begin == end</code>).
     *  - <code>vertices_per_elem</code> is less than one
     *  - <code>element_array</code> is null.
     *  - The range contains invalid handles (non-existent entities,
     *      not an element, etc.)
     *  - Insufficient space in passed array.
     *
     *\param begin        The first element handle
     *\param end          One past the last element handle
     *\param vertices_per_elem Number of vertices to retrieve for each
     *                    element. If the element has more vertices, the
     *                    element connectivity will be truncated. If
     *                    <code>vertices_per_elem</code> is greater than the
     *                    number of nodes for an element, the data will be
     *                    padded with zeros.
     *\param array_size   The length of <code>element_array</code>
     *\param element_array The memory location at which to store the
     *                    connectivity list.
     *\author Jason Kraftcheck
     */
    virtual ErrorCode get_element_connect( Range::const_iterator begin,
                                           const Range::const_iterator& end,
                                           const int vertices_per_elem,
                                           const size_t array_size,
                                           EntityHandle* const element_array ) = 0;

    /** Get poly (polygon or polyhedron) connectivity size
     *\param begin  First iterator in range of poly
     *\param end    One past last in range of poly.
     *\param connectivity_size  The length of the connectivity list
     *              For the specified range of polyhedra.
     *\author Jason Kraftcheck
     */
    virtual ErrorCode get_poly_connect_size( Range::const_iterator begin,
                                             const Range::const_iterator& end,
                                             int& connectivity_size ) = 0;

    /** Get poly (polygon or polyhedron) connectivity.
     *
     * Connectivity is returned in two arrays. The first is
     * an array of global IDs that is the concatenation of the
     * connectivity for the entire range of polys. The second
     * is the last index of the connectivity data for each poly
     * in the global ID array.
     *
     * This function will add as many polys as possible to the
     * passed arrays given the sizes of those arrays. It will
     * then pass back position at which it stopped and the sizes
     * of the data written to the arrays.
     *
     * Failure cases:
     *  - Passed range is empty (<code>begin == end</code>).
     *  - <code>element_array</code> or <code>index_array</code> is null.
     *  - The range contains invalid handles (non-existent entities,
     *      not an poly, etc.)
     *  - Retrieving ID tag for an entity failed.
     *
     *\param iter               As input, the first element handle.
     *                          As output, one past the last element handle
     *                          for which data was written to the arrays.
     *\param end                The iterator at which to stop.
     *\param node_id_tag        A tag with integer values.
     *\param element_array_len  As input, length of <code>element_array</code>.
     *                          As output, the number of entries written in that
     *                          array.
     *\param element_array      The memory location at which to store the
     *                          connectivity list.
     *\param index_array_len    As input, the length of <code>index_array</code>.
     *                          As output, the number of entries written in that
     *                          array.
     *\param index_array        The memory location at which to store offsets.
     *\param index_offset       Value to offset (add to) index values. As output
     *                          the input value plus the amount of data
     *                          written to the element array. (The value you
     *                          presumably want to pass to the next call.)
     *\author Jason Kraftcheck
     */
    virtual ErrorCode get_poly_connect( Range::const_iterator& iter,
                                        const Range::const_iterator& end,
                                        const Tag node_id_tag,
                                        size_t& element_array_len,
                                        int* const element_array,
                                        size_t& index_array_len,
                                        int* const index_array,
                                        int& index_offset ) = 0;

    //! Given elements to be written, gather all the nodes which define those elements
    //! \param elements Range of elements to be written
    //! \param node_bit_mark_tag Bit tag to use to identify nodes
    //! \param nodes Range of nodes gathered from elements (returned)
    //! \return status Return status
    virtual ErrorCode gather_nodes_from_elements( const Range& elements,
                                                  const Tag node_bit_mark_tag,
                                                  Range& nodes ) = 0;

    //! assign ids to input entities starting with start_id, written to id_tag
    //! if id_tag is zero, assigns to GLOBAL_ID_TAG_NAME
    //! \param elements Entities to be written
    //! \param id_tag Tag used to store entity id
    //! \param start_id Starting value for entity ids
    //! \return status Return status
    virtual ErrorCode assign_ids( Range& elements, Tag id_tag, const int start_id ) = 0;

    /** Get explicit adjacencies
     *
     * Get explicit adjacences stored in database.
     * Does not create any explicit adjacencies or search for
     * implicit ones.
     *
     *\param entity  The entity to retrieve adjacencies for.
     *\param id_tag  The global ID tag
     *\param adj     The output list of global IDs of adjacent entities.
     *\author Jason Kraftcheck
     */
    virtual ErrorCode get_adjacencies( EntityHandle entity, Tag id_tag, std::vector< int >& adj ) = 0;

    virtual ErrorCode get_adjacencies( EntityHandle entity, const EntityHandle*& adj_array, int& num_adj ) = 0;

    /**\brief Re-order outgoing element connectivity
     *
     * Permute the connectivity of each element such that the node
     * order is that of the target file format rather than that of MBCN.
     *\param order The permutation to use. Must be an array of 'node_per_elem'
     *             integers and be a permutation of the values [0..node_per_elem-1].
     *             Such that for a single element:
     *             target_conn[i] == mbcn_conn[order[i]]
     *\param conn  The connectivity array to re-order
     *\param num_elem  The number of elements in the connectivity array
     *\param node_per_elem The number of nodes in each element's connectivity list.
     */
    template < typename T >
    static inline void reorder( const int* order, T* conn, int num_elem, int node_per_elem );

    /**\brief Get list of tags to write.
     *
     * Get the list of tags to write to the file, possibly using
     * an optional user-specified tag list. This function consolidates
     * some common code for file writers to use to figure out what
     * tag data to write to the file. It provides the following features:
     *  o filter list based on user-specified array of tag handles
     *  o filter internal tags (those for which the name is prefixed with
     *    two underscore characters)
     *  o filter anonymous tags
     *  o optionally filter variable-length tags.
     *
     *\author Jason Kraftcheck
     *\param result_list List of tag handles for which to write data
     *\param user_tag_list Optional array of tag handles passed by user
     *                     to write to file.
     *\param include_variable_length_tags If false, return only fixed-length
     *                                    tags.
     */
    virtual ErrorCode get_tag_list( std::vector< Tag >& result_list,
                                    const Tag* user_tag_list          = 0,
                                    int user_tag_list_length          = 0,
                                    bool include_variable_length_tags = true ) = 0;

    enum EntityListType
    {
        CONTENTS    = 0,
        CHILDREN    = 1,
        PARENTS     = 2,
        TOPOLOGICAL = 1
    };

    /*\brief Get pointers to internal storage of entity data
     *
     * Get pointers to element connectivity or set content storage.
     *\param query_begin Start of range of entities for which to return results
     *\param query_end   End of range of entities for which to return results.
     *\param output_pointer_array Result list of pointers. Points to either
     *          element connectivity or set contents. Note: set contents
     *          may be in range-compacted format.
     *\param lengths Optional per-entity length of list. If passed, then
     *          always set, for each entity, to the number of values in the
     *          array passed back in \c output_pointer_array
     *\param relation If entity is entity set, which set data to return
     *          (contents array, parent array, or child array). If
     *          entity is an element, then CONTENTS for complete connectivity
     *          or TOPOLOGICAL for only corner vertices.
     *\param flags Optional per-entity flag values. If passed, then
     *          always set to zero for elements and set to set creation
     *          flags for entity sets.
     *\return MB_STRUCTURED_MESH if one or more input elements are stored as
     *          structured mesh and therefore do not have explicit storage.
     *        MB_TYPE_OUT_OF_RANGE if called for vertices.
     */
    virtual ErrorCode get_entity_list_pointers( Range::const_iterator query_begin,
                                                Range::const_iterator query_end,
                                                EntityHandle const** output_pointer_array,
                                                EntityListType relation = CONTENTS,
                                                int* lengths            = 0,
                                                unsigned char* flags    = 0 ) = 0;

    /*\brief Get pointers to internal storage of entity data
     *
     * Get pointers to element connectivity or set content storage.
     *\param entities Pointer to list of entities for which to return results
     *\param num_entities Number of entities in list
     *\param output_pointer_array Result list of pointers. Points to either
     *          element connectivity or set contents. Note: set contents
     *          may be in range-compacted format.
     *\param lengths Optional per-entity length of list. If passed, then
     *          always set, for each entity, to the number of values in the
     *          array passed back in \c output_pointer_array
     *\param relation If entity is entity set, which set data to return
     *          (contents array, parent array, or child array). If
     *          entity is an element, then CONTENTS for complete connectivity
     *          or TOPOLOGICAL for only corner vertices.
     *\param flags Optional per-entity flag values. If passed, then
     *          always set to zero for elements and set to set creation
     *          flags for entity sets.
     *\return MB_STRUCTURED_MESH if one or more input elements are stored as
     *          structured mesh and therefore do not have explicit storage.
     *        MB_TYPE_OUT_OF_RANGE if called for vertices.
     */
    virtual ErrorCode get_entity_list_pointers( EntityHandle const* entities,
                                                int num_entities,
                                                EntityHandle const** output_pointer_array,
                                                EntityListType relation = CONTENTS,
                                                int* lengths            = 0,
                                                unsigned char* flags    = 0 ) = 0;
};

template < typename T >
inline void WriteUtilIface::reorder( const int* order, T* conn, int num_elem, int node_per_elem )
{
    std::vector< T > elem( node_per_elem );
    T* const end = conn + num_elem * node_per_elem;
    while( conn != end )
    {
        std::copy( conn, conn + node_per_elem, elem.begin() );
        for( int j = 0; j < node_per_elem; ++j, ++conn )
            *conn = elem[order[j]];
    }
}

}  // namespace moab

#endif