{"id":28336,"date":"2016-02-24T16:24:29","date_gmt":"2016-02-24T16:24:29","guid":{"rendered":"https:\/\/www.padtinc.com\/2016\/02\/24\/reading-ansys-mechanical-rst-c-cpp-part3\/"},"modified":"2022-03-24T22:51:13","modified_gmt":"2022-03-24T22:51:13","slug":"reading-ansys-mechanical-rst-c-cpp-part3","status":"publish","type":"post","link":"https:\/\/www.padtinc.com\/2016\/02\/24\/reading-ansys-mechanical-rst-c-cpp-part3\/","title":{"rendered":"Reading ANSYS Mechanical Result Files (.RST) from C\/C++ (Part 3)"},"content":{"rendered":"

\"ansys-fortran-to-c-cpp-1-00\" <\/picture><\/a>In the last post <\/a>of this series I illustrated how I handled the nested call structure of the procedural interface to ANSYS\u2019 BinLib routines.\u00a0 If you recall, any time you need to extract some information from an ANSYS result file, you have to bracket the function call that extracts the information with a *Begin and *End set of function calls.\u00a0 These two functions setup and tear down internal structures needed by the FORTRAN library.\u00a0 I showed how I used RAII principles in C++ along with a stack data structure to manage this pairing implicitly.\u00a0 However, I have yet to actually read anything truly useful off of the result file!\u00a0 This post centers on the design of a set of C++ iterators that are responsible for actually reading data off of the file.\u00a0 By taking the time to write iterators, we expose the ANSYS RST library to many of the algorithms available within the standard template library (STL), and we also make our own job of writing custom algorithms that consume result file data much easier.\u00a0 So, I think the investment is worthwhile.<\/p>\n

If you\u2019ve programmed in C++ within the last 10 years, you\u2019ve undoubtedly been exposed to the standard template library.\u00a0 The design of the library is really rather profound.\u00a0 This image represents the high level design of the library in a pictorial fashion:<\/p>\n

\"ansys-fortran-to-c-cpp-3-01\" <\/picture><\/a><\/p>\n

On one hand, the library provides a set of generic container objects that provide a robust implementation of many of the classic data structures available within the field of computer science.\u00a0 The collection of containers includes things like arbitrarily sized contiguous arrays (vectors), linked lists, associative arrays, which are implemented as either binary trees or as a hash container, as well as many more.\u00a0 The set of containers alone make the STL quite valuable for most programmers.<\/p>\n

On the other hand, the library provides a set of generic algorithms that encompass a whole suite of functionality defined in classic computer science.\u00a0 Sorting, searching, rearranging, merging, etc\u2026 are just a handful of the algorithms provided by the library.\u00a0 Furthermore, extreme care has been taken within the implementation of these algorithms such that an average programmer would hard pressed to produce something safer and more efficient on their own.<\/p>\n

However, the real gem of the standard library are iterators.\u00a0 Iterators bridge the gap between generic containers on one side and the generic algorithms on the other side.\u00a0 Need to sort a vector of integers, or a double ended queue of strings?\u00a0 If so, you just call the same sort function and pass it a set of iterators.\u00a0 These iterators \u201cknow\u201d how to traverse their parent container.\u00a0 (Remember containers are the data structures.)<\/p>\n

So, what if we could write a series of iterators to access data from within an ANSYS result file?\u00a0 What would that buy us?\u00a0 Well, depending upon which concepts our iterators model, having them available would open up access to at least some of the STL suite of algorithms.\u00a0 That\u2019s good.\u00a0 Furthermore, having iterators defined would open up the possibility of providing range objects.\u00a0 If we can provide range objects, then all of the sudden range based for loops are possible.\u00a0 These types of loops are more than just syntactic sugar.\u00a0 By encapsulating the bounds of iteration within a range, and by using iterators in general to perform the iteration, the burden of a correct implementation is placed on the iterators themselves.\u00a0 If you spend the time to get the iterator implementation correct, then any loop you write after that using either the iterators or better yet the range object will implicitly be correct from a loop construct standpoint.\u00a0 Range based for loops also make your code cleaner and easier to reason about locally.<\/p>\n

Now for the downside\u2026\u00a0 Iterators are kind of hard to write.\u00a0 The price for the flexibility they offer is paid for in the amount of code it takes to write them.\u00a0 Again, though, the idea is that you (or, better yet somebody else) writes these iterators once and then you have them available to use from that point forward.<\/p>\n

Because of their flexibility, standard conformant iterators come in a number of different flavors.\u00a0 In fact, they are very much like an ice cream Sunday where you can pick and choose what features to mix in or add on top.\u00a0 This is great, but again it makes implementing them a bit of a chore.\u00a0 Here are some of the design decisions you have to answer when implementing an iterator:<\/p>\n\n\n\n\n\n
Decision<\/td>\nOptions<\/td>\nChoice for RST Reader Iterators<\/td>\n<\/tr>\n
Dereference Data Type<\/td>\nAnything you want<\/td>\nSpecial structs for each type of iterator.<\/td>\n<\/tr>\n
Iteration Category<\/td>\n1.\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Forward iterator
\n2.\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Single pass iterator
\n3.\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Bidirectional iterator
\n4.\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Random access iterator<\/td>\n		Forward, Single Pass<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Iterators syntactically function much like pointers in C or C++.\u00a0 That is, like a pointer you can increment an iterator with the ++ operator, you can dereference an iterator with the * operator and you can compare two iterators for equality.\u00a0 We will talk more about incrementing and comparisons in a minute, but first let\u2019s focus on dereferencing.\u00a0 One thing we have to decide is what type of data the client of our iterator will receive when they dereference it.\u00a0 My choice is to return a simple C++ structure with data members for each piece of data.\u00a0 For example, when we are iterating over the nodal geometry, the RST file contains the node number, the nodal coordinates and the nodal rotations.\u00a0 To represent this data, I create a structure like this:\"ansys-fortran-to-c-cpp-3-02\" <\/picture><\/a><\/p>\n

I think this is pretty self-explanatory. \u00a0Likewise, if we are iterating over the element geometry section of an RST file, there is quite a bit of useful information for each element.\u00a0 The structure I use in that case looks like this:<\/p>\n

\"ansys-fortran-to-c-cpp-3-03\" <\/picture><\/a><\/p>\n

 <\/p>\n

Again, pretty self-explanatory.\u00a0 So, when I\u2019m building a node geometry iterator, I\u2019m going to choose the NodalCoordinateData structure as my dereference type.<\/p>\n

The next decision I have to make is what \u201ckind\u201d of iterator I\u2019m going to create.\u00a0 That is, what types of \u201citeration\u201d will it support?\u00a0 The C++ standard supports a variety of iterator categories.\u00a0 You may be wondering why anyone would ever care about an \u201citeration category\u201d?\u00a0 Well, the reason is fundamental to the design of the STL.\u00a0\u00a0 Remember that the primary reason iterators exist is to provide a bridge between generic containers and generic algorithms.\u00a0 However, any one particular algorithm may impose certain requirements on the underlying iterator for the algorithm to function appropriately.<\/p>\n

Take the algorithm \u201csort\u201d for example.\u00a0 There are, in fact, lots of different \u201csort\u201d algorithms.\u00a0 The most efficient versions of the \u201csort\u201d algorithm require that an iterator be able to jump around randomly in constant time within the container.\u00a0 If the iterator supports jumping around (a.k.a. random access) then you can use it within the most efficient sort algorithm.\u00a0 \u00a0However, there are certain kinds of iterators that don\u2019t support jumping around.\u00a0 Take a linked list container as an example.\u00a0 You cannot randomly jump around in a linked list in constant time.\u00a0 To get to item B from item A you have to follow the links, which means you have to jump from link to link to link, where each jump takes some amount of processing time.\u00a0 This means, for example, there is no easy way to cut a linked list exactly in half even if you know how many items in total are in the list.\u00a0 To cut it in half you have to start at the beginning and follow the links until you\u2019ve followed size\/2 number of links.\u00a0 At that point you are at the \u201ccenter\u201d of the list.\u00a0 However, with an array, you simply choose an index equal to size\/2 and you automatically get to the center of the array in one step. \u00a0Many sort algorithms, as an example, obtain their efficiency by effectively chopping the container into two equal pieces and recursively sorting the two pieces.\u00a0 You lose all that efficiency if you have to walk out to the center.<\/p>\n

If you look at the \u201ctypes\u201d of iterators in the table above you will see that they build upon one another.\u00a0 That is, at the lowest level, I have to answer the question, can I just move forward one step?\u00a0 If I can\u2019t even do that, then I\u2019m not an iterator at all.\u00a0 After that, assuming I can move forward one step, can I only go through the range once, or can I go over the range multiple times?\u00a0 If I can only go over the range once, I\u2019m a single pass iterator.\u00a0 Truthfully, the forward iterator concept and the single pass iterator concept form level 1A and 1B of the iterator hierarchy.\u00a0 The next higher level of functionality is a bidirectional iterator.\u00a0 This type of iterator can go forward and backwards one step in constant time.\u00a0 Think of a doubly linked list.\u00a0 With forward and backward links, I can go either direction one step in constant time.\u00a0 Finally, the most flexible iterator is the random access iterator.\u00a0 These are iterators that really are like raw pointers.\u00a0 With a pointer you can perform pointer arithmetic such that you can add an arbitrary offset to a base pointer and end up at some random location in a range.\u00a0 It\u2019s up to you to make sure that you stay within bounds.\u00a0 Certain classes of iterators provide this level of functionality, namely those associated with vectors and deques.<\/p>\n

So, the question is what type of iterator should we support?\u00a0 Perusing through the FORTRAN code shipped with ANSYS, there doesn\u2019t appear to be an inherent limitation within the functions themselves that would preclude random access.\u00a0 But, my assumption is that the routines were designed to access the data sequentially.\u00a0 (At least, if I were the author of the functions that is what I would expect clients to do.) \u00a0So, I don\u2019t know how well they would be tested regarding jumping around.\u00a0 Furthermore, disk controllers and disk subsystems are most likely going to buffer the data as it is read, and they very likely perform best if the data access is sequential. \u00a0So, even if it is possible to randomly jump around on the result file, I\u2019m not sold on it being a good idea from a performance standpoint.\u00a0 Lastly, I explicitly want to keep all of the data on the disk, and not buffer large chunks of it into RAM within my library.\u00a0 So, I settled on expressing my iterators as single pass, forward iterators.\u00a0 These are fairly restrictive in nature, but I think they will serve the purpose of reading data off of the file quite nicely.<\/p>\n

Regarding my choice to not buffer the data, let me pause for a minute and explain why I want to keep the data on the disk. First, in order to buffer the data from disk into RAM you have to read the data off of the disk one time to fill the buffer.\u00a0 So, that process automatically incurs one disk read.\u00a0 Therefore, if you only ever need to iterate over the data once, perhaps to load it into a more specialized data structure, buffering it first into an intermediate RAM storage will actually slow you down, and consume more RAM.<\/strong>\u00a0 The reason for this is that you would first iterate over the data stored on the disk and read it into an intermediate buffer.\u00a0 Then, you would let your client know the data is ready and they would iterate over your internal buffer to access the data.\u00a0 They might as well just read the data off the disk themselves! If the end user really wants to buffer the data, that\u2019s totally fine.\u00a0 They can choose to do that themselves, but they shouldn\u2019t have to pay for it if they don\u2019t need it.<\/p>\n

Finally, we are ready to implement the iterators themselves.\u00a0 To do this I rely on a very high quality open source library called Boost.\u00a0 Boost has within it a library called iterator_facade that takes care of supplying most all of the boilerplate code needed to create a conformant iterator.\u00a0 Using it has proven to be a real time saver.\u00a0 To define the actual iterator, you derive your iterator class from iterator_facade and pass it a few template parameters.\u00a0 One is the category defining the type of iterator you are creating.\u00a0 Here is the definition for the nodal geometry iterator:<\/p>\n

\"ansys-fortran-to-c-cpp-3-04\" <\/picture><\/a><\/p>\n

You can see that there are a few private functions here that actually do all of the work.\u00a0 The function \u201cincrement\u201d is responsible for moving the iterator forward one spot.\u00a0 The function \u201cequal\u201d is responsible for determining if two different iterators are in fact equal.\u00a0 And the function \u201cdereference\u201d is used to return the data associated with the current iteration spot.\u00a0 You will also notice that I locally buffer the single piece of data associated with the current location in the iteration space inside the iterator.\u00a0 This is stored in the pData member function.\u00a0 I also locally store the current index.\u00a0\u00a0 Here are the implementations of the functions just mentioned:<\/p>\n

\"ansys-fortran-to-c-cpp-3-05\" <\/picture><\/a><\/p>\n

First you can see that testing iterator equality is easy.\u00a0 All we do is just look to see if the two iterators are pointing to the same index.\u00a0 If they are, we define them as equal. (Note, an important nuance of this is that we don\u2019t test to see if their buffered data is equal, just their index.\u00a0 This is important later on.)\u00a0 Likewise, increment is easy to understand as well.\u00a0 We just increase the index by one, and then buffer the new data off of disk into our local storage.\u00a0 Finally, dereference is easy too.\u00a0 All we do here is just return a reference to the local data store that holds this one node\u2019s data.\u00a0 The only real work occurs in the readData() function.\u00a0 Inside that function you will see the actual call to the CResRdNode() function.\u00a0 We pass that function our current index and it populates an array of 6 doubles with data and returns the actual node number.\u00a0 After we have that, we simply parse out of that array of 6 doubles the coordinates and rotations, storing them in our local storage.\u00a0 That\u2019s all there is to it.\u00a0 A little more work, but not bad.<\/p>\n

With these handful of operations, the boost iterator_facade class can actually build up a fully conformant iterator will all the proper operator overloads, etc\u2026 It just works.\u00a0 Now that we have iterators, we need to provide a \u201cbegin\u201d and \u201cend\u201d function just like the standard containers do.\u00a0 These functions should return iterators that point to the beginning of our data set and to one past the end of our data set.\u00a0 You may be thinking to yourself, wait a minute, how to we provide an \u201cend\u201d iterator without reading the whole set of nodes?\u00a0 The reality is, we just need to provide an iterator that \u201cequality tests\u201d to be equal to the end of our iteration space?\u00a0 What does that mean?\u00a0 Well, what it means is that we just need to provide an iterator that, when compared to another iterator which has walked all the way to the end, it passes the \u201cequal\u201d test.\u00a0 Look at the \u201cequal\u201d function above.\u00a0 What do two iterators need to have in common to be considered equal?\u00a0 They need to have the same index.\u00a0 So, the \u201cend\u201d iterator simply has an index equal to one past the end of the iteration space.\u00a0 We know how big our iteration space is because that is one of the pieces of metadata supplied by those ResRd*Begin functions.\u00a0 So, here are our begin\/end functions to give us a pair of conformant iterators.<\/p>\n

\"ansys-fortran-to-c-cpp-3-06\" <\/picture><\/a><\/p>\n

Notice, that the nodes_end() function creates a NodeIterator and passes it an index that is one past the maximum number of nodes that have coordinate data stored on file.\u00a0 You will also notice, that it does not have a second Boolean argument associated with it.\u00a0 I use that second argument to determine if I should immediately read data off of the disk when the iterator is constructed.\u00a0 For the begin iterator, I need to do that.\u00a0 For the end iterator, I don\u2019t actually need to cache any data.\u00a0 In fact, no data for that node is defined on disk.\u00a0 I just need a sentinel iterator that is one past the iteration space.<\/p>\n

So, there you have it.\u00a0 Iterators are defined that implicitly walk over the rst file pulling data off as needed and locally buffering one piece of it.\u00a0 These iterators are standard conformant and thus can be used with any STL algorithm that accepts a single pass, read only, forward iterator.\u00a0 They are efficient in time and storage.\u00a0 There is, though, one last thing that would be nice.\u00a0 That is to provide a range object so that we can have our cake and eat it too.\u00a0 That is, so we can write these C++11 range based for loops.\u00a0 Like this:\"ansys-fortran-to-c-cpp-3-07\" <\/picture><\/a><\/p>\n

To do that we need a bit of template magic.\u00a0 Consider this template and type definition:<\/p>\n

\"ansys-fortran-to-c-cpp-3-08\" <\/picture><\/a><\/p>\n

There is a bit of machinery that is going on here, but the concept is simple.\u00a0 I just want the compiler to stamp out a new type that has a \u201cbegin()\u201d and \u201cend()\u201d member function that actually call my \u201cnodes_begin()\u201d and \u201cnodes_end()\u201d functions.\u00a0 That is what this template will do.\u00a0 I can also create a type that will call my \u201celements_begin()\u201d and \u201celements_end()\u201d function.\u00a0 Once I have those types, creating range objects suitable for C++11 range based for loops is a snap.\u00a0 You just make a function like this:<\/p>\n

\"ansys-fortran-to-c-cpp-3-09\" <\/picture><\/a><\/p>\n

 <\/p>\n

This function creates one of these special range types and passes in a pointer to our RST reader.\u00a0 When the compiler then sees this code:<\/p>\n

\"ansys-fortran-to-c-cpp-3-10\" <\/picture><\/a><\/p>\n

It sees a range object as the return type of the \u201cnodes()\u201d function.\u00a0 That range object is compatible with the semantics of range based for loops, and therefore the compiler happily generates code for this construction.<\/p>\n

Now, after all of this work, the client of the RST reader library can open a result file, select something of interest, and start looping over the items in that category; all in three lines of code.\u00a0 There is no need to understand the nuances of the binlib functions.\u00a0 But best of all, there is no appreciable performance hit for this abstraction.\u00a0 At the end of the day, we\u2019re not computationally doing anything more than what a raw use of the binlib functions would perform.\u00a0 But, we\u2019re adding a great deal of type safety, and, in my opinion, readability to the code.\u00a0 But, then again, I\u2019m only slightly partial to C++.\u00a0 Your mileage may vary\u2026<\/p>\n","protected":false},"excerpt":{"rendered":"

In the last post of this series I illustrated how I handled the nested call structure of the procedural interface […]<\/p>\n","protected":false},"author":8,"featured_media":28309,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2323],"tags":[478,511,492,1219,1156,1220,1221,1222,1223],"post-podcast":[],"_links":{"self":[{"href":"https:\/\/www.padtinc.com\/wp-json\/wp\/v2\/posts\/28336"}],"collection":[{"href":"https:\/\/www.padtinc.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.padtinc.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.padtinc.com\/wp-json\/wp\/v2\/users\/8"}],"replies":[{"embeddable":true,"href":"https:\/\/www.padtinc.com\/wp-json\/wp\/v2\/comments?post=28336"}],"version-history":[{"count":0,"href":"https:\/\/www.padtinc.com\/wp-json\/wp\/v2\/posts\/28336\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.padtinc.com\/wp-json\/wp\/v2\/media\/28309"}],"wp:attachment":[{"href":"https:\/\/www.padtinc.com\/wp-json\/wp\/v2\/media?parent=28336"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.padtinc.com\/wp-json\/wp\/v2\/categories?post=28336"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.padtinc.com\/wp-json\/wp\/v2\/tags?post=28336"},{"taxonomy":"post-podcast","embeddable":true,"href":"https:\/\/www.padtinc.com\/wp-json\/wp\/v2\/post-podcast?post=28336"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}