libuserd_interface.h | Ansys Developer Portal

/*
 *
 *  *************************************************************
 *   Copyright 2024 ANSYS, Inc.
 *   All Rights Reserved.
 *
 *        Restricted Rights Legend
 *
 *   Use, duplication, or disclosure of this
 *   software and its documentation by the
 *   Government is subject to restrictions as
 *   set forth in subdivision [(b)(3)(ii)] of
 *   the Rights in Technical Data and Computer
 *   Software clause at 52.227-7013.
 *  *************************************************************
 */
 
#ifndef USERD_INTERFACE_H
#define USERD_INTERFACE_H
 
#ifdef __cplusplus
 
#include <string>
#include <vector>
#include <map>
#include <array>
 
/* TODO
 *  - Add support for structured data
 */
 
namespace libuserd {
 
    enum ElementType {
        POINT,
        POINT_GHOST,
        BAR02,
        BAR02_GHOST,
        BAR03,
        BAR03_GHOST,
        TRI03,
        TRI03_GHOST,
        TRI06,
        TRI06_GHOST,
        QUAD04,
        QUAD04_GHOST,
        QUAD08,
        QUAD08_GHOST,
        TET04,
        TET04_GHOST,
        TET10,
        TET10_GHOST,
        PYR05,
        PYR05_GHOST,
        PYR13,
        PYR13_GHOST,
        PENT6,
        PENT6_GHOST,
        PENT15,
        PENT15_GHOST,
        HEX08,
        HEX08_GHOST,
        HEX20,
        HEX20_GHOST,
        NSIDED,
        NSIDED_GHOST,
        NFACED,
        NFACED_GHOST,
        MAX_ELEMENT_TYPE
    };
 
    enum VariableLocation {
        DATASET,
        PART,
        NODE,
        ELEMENT,
        UNKNOWN_LOCATION
    };
 
    enum VariableType {
        CONSTANT,
        SCALAR,
        VECTOR,
        TENSOR,
        TENSOR9,
        UNKNOWN_VAR_TYPE
    };
 
    enum PartHints {
        STATIC_COORDS = (1 << 0),
        CHANGING_COOORDS = (1 << 1),
        CHANGING_CONNECTIVITY = (1 << 2)
    };
 
    enum ErrorCode {
        SUCCESS = 0,   
        UNAVAILABLE = 1, 
        IGNORED_AFTER_INITIALIZE = 2, 
        OUT_OF_MEMORY = 3, 
        IO = 4, 
        UNIMPLEMENTED = 5, 
        NOT_FOUND = 6, 
        UNKNOWN = 7,   
        SINGLE_READER_ALLOWED = 8  
    };
 
    // The "options" structure
    struct OptBoolean {
        const std::string name;
        int32_t value;
        const int32_t default_value;
 
        // Constructor to initialize the struct
        OptBoolean(const std::string& _name, int32_t _value, int32_t _default_value)
            : name(_name), value(_value), default_value(_default_value) {
        }
    };
 
    struct OptOption {
        const std::string name;
        const std::vector<std::string> values;
        uint32_t value_index;
        const uint32_t default_value_index;
 
        // Constructor to initialize the struct
        OptOption(const std::string& _name, const std::vector<std::string>& _value, uint32_t _val_index, uint32_t _default_value_index)
            : name(_name), values(_value), value_index(_val_index), default_value_index(_default_value_index) {
        }
    };
 
    struct OptField {
        const std::string name;
        std::string value;
        const std::string default_value;
 
        // Constructor to initialize the struct
        OptField(const std::string& _name, const std::string& _value, const std::string& _default_value)
            : name(_name), value(_value), default_value(_default_value) {
        }
    };
 
    struct Options {
        std::vector<struct OptBoolean> booleans;
        std::vector<struct OptOption> options;
        std::vector<struct OptField> fields;
    };
 
    struct fileExtensions {
        std::string name;
        std::vector<std::string> file_1_extension;
        std::vector<std::string> file_2_extension;
    };
 
    // Forward declaration
    class ReaderInfo;
    class LibUserd;
    class Reader;
 
    class Query {
 
    public:
        const uint32_t m_id;  
        const std::string m_name;  
        const std::string m_x_title;  
        const std::string m_y_title;  
        std::map<const std::string, std::string> m_metadata;  
 
        size_t num_points();
 
         ErrorCode data(float* x, float* y);
 
         std::string to_string();
 
    private:
        Query(const uint32_t id,
              const uint32_t reader_id,
              const std::string& name,
              const std::string& x_title,
              const std::string& y_title,
              const std::map<const std::string, std::string>& metadata);
        friend class Reader;
        uint32_t m_reader_id;
        float m_reader_version;
    };
 
    class Variable {
 
    public:
        const uint32_t id;  
        const std::string name;  
        const std::string unit_label; 
        const std::string unit_dims;  
        const VariableLocation location; 
        const VariableType type;  
        const bool time_varying;  
        const bool complex;  
        const bool interleave_flag; 
        const uint32_t number_of_components; 
        std::map<const std::string, std::string> metadata;  
 
        static std::string get_variable_type_string(VariableType vtype);
 
        static std::string get_variable_location_string(VariableLocation location);
 
        std::string is_true(bool val);
 
        std::string to_string();
 
    private:
        Variable(const uint32_t _id,
            const std::string& _name,
            const std::string& _unit_label,
            const std::string& _unit_dims,
            const VariableLocation _location,
            const VariableType _type,
            const bool _time_varying,
            const bool _complex,
            const bool _interleave_flag,
            const uint32_t _number_of_components,
            const std::map<const std::string, std::string>& _metadata);
 
        friend class Reader;
    };
 
    struct RigidBodyTransform {
        float translation[3];  
        float euler_value[4];  
        float center_of_gravity[3];  
        float rotation_order;  
        float rotation_angles[3];  
    };
 
    class Part {
 
    public:
        const uint32_t m_index; 
        const uint32_t m_id; 
        const uint32_t m_reader_id; 
        const std::string m_name; 
        std::map<const std::string, std::string> m_metadata; 
        const PartHints m_hints;   
        float m_reader_api_version; 
 
         ErrorCode num_nodes(std::size_t& num_coords);
 
         ErrorCode nodes(float* xyz);
 
 
         ErrorCode num_elements(std::map<ElementType, std::size_t>& elements);
 
         
 
         ErrorCode element_conn(ElementType elem_type, uint32_t* connectivity);
 
         ErrorCode element_conn_nsided_size(ElementType elem_type, 
            size_t& nodes_per_polygon_size, size_t& nodes_size);
 
         ErrorCode element_conn_nsided(ElementType elem_type, uint32_t* nodes_per_polygon, uint32_t* nodes);
 
          ErrorCode element_conn_nfaced_size(ElementType elem_type, size_t& faces_per_element_size,
             size_t& nodes_per_face_size, size_t& indices_size);
 
         ErrorCode element_conn_nfaced(ElementType elem_type,
            uint32_t* faces_per_element, uint32_t* nodes_per_face, uint32_t* nodes);
 
         ErrorCode variable_values(Variable* var, ElementType elem_type, 
            bool complex, uint32_t component, float* array);
 
         ErrorCode rigid_body_transform(struct RigidBodyTransform& transform);
 
    private:
        Part(const uint32_t index,
            const uint32_t id,
            const uint32_t reader_id,
            const std::string& name,
            const std::map<const std::string, std::string>& metadata,
            const PartHints hints);
 
        friend class Reader;
    };
 
 
    class ReaderInfo {
 
    public:
        const uint32_t m_id;  
        const std::string m_name;   
        const std::string m_description;  
        const std::string m_file_labels[2];  
        struct Options m_options;  
 
        ErrorCode read_dataset(const std::string& file1, const std::string& file2, bool use_parallel, Reader*& reader);
 
        std::string to_string();
 
 
        static bool get_userd_xtra_gui_values(int reader_id, Options& userd_options);
 
    private:
        ReaderInfo(const uint32_t id,
            const std::string name,
            const std::string description,
            const std::string file_labels[2],
            struct Options options);
        friend class LibUserd;
    };
 
    class Reader {
 
    public:
        const std::string m_unit_system; 
        std::map<const std::string, std::string> m_metadata;  
        std::string m_raw_metadata; 
 
        static uint32_t s_curr_time_step; // ToDo: Should be removed later
        static uint32_t s_curr_time_set; // ToDo: Should be removed later
 
         ErrorCode parts(std::vector<Part*>& part_list);
 
         ErrorCode variables(std::vector<Variable*>& variable_list);
 
         ErrorCode queries(std::vector<Query*>& query_list);
 
         
         ErrorCode get_number_of_time_sets(uint32_t & number_of_time_sets);
 
         ErrorCode timevalues(std::vector<float> & timevalues, uint32_t timeset_number = 0);
 
         ErrorCode set_timevalue(float timevalue, uint32_t timeset_number = 0);
 
          ErrorCode set_timestep(uint32_t timestep, uint32_t timeset_number = 0);
 
 
         ErrorCode variable_value(const Variable* var, float& value);
 
 
         bool is_geometry_changing();
 
          const ReaderInfo* info();
 
          // static helper methods
          static ErrorCode get_geometry_info(int reader_id, int part_index, std::vector<int>& geoms_vector);
          static ErrorCode number_of_geometries(int reader_id, int part_index, int& number_of_geoms);
 
 
    private:
        Reader(ReaderInfo info);
        friend class ReaderInfo;
        float m_reader_version;
 
        ReaderInfo m_reader_info;   
 
        // Private helper methods
        ErrorCode get_meta_data_string();
        void parse_metatags(std::map<const std::string, std::string>& map, const char* section_name);
        ErrorCode get_part_hints(int reader_id, int part_index, PartHints& part_hints);
 
        std::map<const std::string, std::string> m_part_metatags;
        std::map<const std::string, std::string> m_var_metatags;
        std::map<const std::string, std::string> m_query_metatags;
    };
 
 
    class LibUserd {
    public:
 
         static LibUserd* library_interface();
 
 
         static Reader* get_active_reader();
 
        static std::string errorcode_as_string(ErrorCode code);
 
        static size_t nodes_per_element(ElementType elem_type);
 
        static bool element_is_ghost(ElementType elem_type);
 
        static bool element_is_zoo(ElementType elem_type);
 
        static bool element_is_nsided(ElementType elem_type);
 
        static bool element_is_nfaced(ElementType elem_type);
 
        static size_t number_of_simple_element_types();
 
        static const std::string& library_version();
 
        static const std::string& ansys_release_string();
 
        static uint32_t ansys_release_number();
 
 
        //ToDo: Will convert this to const & later (I need add a map or something inside the class to do this)
        static const std::string element_type_to_string(ElementType type);
 
        /*
         * These functions need to be called before initialize() is called.
         */
 
        ErrorCode set_reader_path(const std::string& path);
 
        /*
         * EnSight USERD readers include a mechanism where they can exchange information between instances.
         * This is used for parallel I/O operations, where each process reads an independent portion of the data.
         * Since each Reader instance is in a different process a communications channel needs to be supplied
         * by the host application to support this.  When run this way, every process has a "rank".  For example,
         * if you want to read 5 way parallel, you will have 5 processes and they will be ranks: [0,1,2,3,4].
         * It is not important which processes have which ranks, only that all of the ranks exist once and only
         * once.
         *
         * To run libuserd in parallel one must call one of the set_reduction calls before calling initialize().
         *
         * Options include:
         * 1) a custom proc that the application provide (e.g. an MPI implementation).
         * 2) TCP/IP where rank 0 manages the operations and all other ranks connect to it.
         * 3) a shared filesystem implementation where rank 0 manages operations and uses a
         *    common filesystem as the communication scheme.
         */
 
        enum ReduceOp {
            SUM = 0,
            MIN = 1,
            MAX = 2,
            ABSMIN = 3,
            ABSMAX = 4,
            BROADCAST = 5
        } z_reduce_ops;
 
        enum ReduceDataType {
            FLOAT = 0,
            DOUBLE = 1,
            INT = 2,
            UCHAR = 3
        };
 
        using ReduceProc = ErrorCode(*) (ReduceOp op, uint32_t number_of_values, ReduceDataType type, void* data, uint32_t count, void* userdata);
        
        // redirection of error handling output
 
        enum SeverityLevel {
            LVL_INFO = 0,
            LVL_WARN = 1,
            LVL_ERROR = 2,
            LVL_FATAL = 3,
            LVL_UNKNOWN = 4
        };
 
        static const std::string severity_level_to_string(SeverityLevel level);
 
        using ErrorProc = ErrorCode(*) (const char* message, SeverityLevel severity_level, void* userdata);
 
        ErrorCode set_reduction(ReduceProc func, uint32_t rank, uint32_t num_ranks, void* userdata);
 
 
        ErrorCode set_reduction(uint32_t rank_0_port, const std::string& rank_0_hostname,
            uint32_t rank, uint32_t num_ranks);
 
        ErrorCode set_reduction(const std::string& directoryname, uint32_t rank, uint32_t num_ranks);
 
        ErrorCode set_message_handler(ErrorProc, void* userdata);
 
        ErrorCode initialize();
 
        static size_t get_available_reader_count();
 
        ErrorCode get_all_readers(std::vector<ReaderInfo>& info);
 
        ErrorCode query_format(const std::string& name1, const std::string& name2, std::vector<ReaderInfo>& reader_info);
 
        ErrorCode shutdown();
 
 
         bool is_initialized() const;
 
        ~LibUserd();
 
    private:
        LibUserd();
        LibUserd(const LibUserd&) = delete;
        bool m_is_initialized;
        static std::string s_libuserd_interface_version;
        static std::string s_ansys_release_version_string;
        static uint32_t s_ansys_release_version_number;
        static LibUserd* m_libuserd;
 
        friend class ReaderInfo;
        static void set_active_reader(Reader* reader);
        static Reader* m_active_reader;
 
        std::vector<fileExtensions> ReaderExtension;
        void initReaderExtensions();
        std::string processFilename(const std::string &filename);
    };
 
}
 
#endif
 
#endif
Post-processing tools 2025 R1

libuserd_interface

Connect with Ansys
