My name is Jim Dempsey. My introduction to the Array Visualizer was entirely by accident. I required a decent FORTRAN 90 compiler on a Windows platform. And by chance I chose the Intel compiler over trying to hack in a "free" open source compiler. Mainly I wanted the 1-year support contract to help with the growing pains. I haven't programmed in FORTRAN in over 30 years. The project I wanted to convert was a program written as an evolutionary process and is now produced on a Mac in F77. I wanted F90 on Windows.
In addition to sprucing it up to F90 with major rewrite of data layouts (fixed size COMMON blocks to allocated memory) I also wanted to add some graphics capabilities. The old code pumped output into a database and then you had to write a post processor to construct a visualization of the run. This may have been OK for the designer of the original program but it was not suitable for my needs.
My requirements were to see a visualization of the simulation as the simulation was churning out the data. This would permit me to observe what is happening during the run and to formulate corrective action during the run rather than as a post mortem dump-like process.
Originally I had intended to try to integrate Blender into the F90 program. But the Blender documentation (in regards to program interface) was (is?) in worse shape than the AV FORTRAN documentation (which sad to say is not very well written). At first I was hesitant at integrating AV into the application. It seemed too restrictive (at least what was available from the documentation). Virtually all the documentation, including examples, showed static graphs. What I needed was dynamic graphs (animated graphs). Last year none of the examples illustrated an animated graph. This year there is an example but it is not written in F90.
Almost by accident I came across avUpdate the documentation only indicates you can use this call to inform AV that a change occurred in data tables that AV should know about. I put 2 + 2 together and concluded that AV could be used to animate graphs.
Getting the graphs to animate was a steep learning curve. Due to the lack of adequate documentation.
After much work and effort I am extremely pleased with the capabilities of AV. The application now presents graphs, some of which contain upwards of 59 plots, all but one of which are dynamic plots.
Now for a bit of constructive criticism.
As a (formerly) new user to Array Visualizer from the FORTRAN user's view point I can only say that the documentation sucks almost to complete vacuum.
The problems lie in much of the FORTRAN interface is not in the Index. You can find most of the subroutine names with a search. But then you need to know or guess at the name. Then when you get to the topic, few are written well enough to explain the use of the function. Most are documented not better than the INTERFACE sections in the header files.
The biggest obstacle is, all the interface calls document a principal argument, object, as the opaque object. i.e. there is no description as to what the object is or how you extract the object handle from the database maintained by AV.
In order to derive this information I typically had to search the sample programs for use. Often a Java script file had a reference to the function of interest. In some cases the FORTRAN call could be figured out by one line of the .js file. But in other cases a little bit of reverse engineering was require to go back up the object tree in .js and then came the job of bringing this back down to a conversion back into FORTRAN.
Example:
subroutine avSetViewpoint(object, coord, val, status)
integer(int_ptr_kind()), intent(IN) :: object
integer, intent(IN) :: coord
real(8), intent(IN) :: val
integer, intent(OUT) :: status
end subroutine avSetViewpoint
What is object. I know it is the camera but (for FORTRAN) just how do I go about getting the object handle for the camera.
So... I look in the index under camera. I find: center of interest, orientation, view angel, viewpoint. I also find Camera property and CameraUpdate event. None of the topic titles indicate something that would extract the camera handle from the AV database. Hmm... not in the index.
Well... I know most, if not all AV function/subroutine names are prefixed by Av So... I enter in AvCamera. I find AvCamera object. Which tells me the properties and methods of how to use a camera but it does not tell be how to obtain the camera object handle.
So... I put in a search for "camera" and I find 15 topics that require the camera object handle but none that tell how to obtain the camera object handle. Hmm... not in search...
So... I use Visual Studion IDE editor to search for "camera" in all the files starting at "C:\Program Files\Intel" and try to pick out sample uses and then try to reverse engineer the syntax from an example, most of which are not in FORTRAN.
I discover that the proper FORTRAN subroutine is avCamera. What??? I looked for avCamera in the index and found it. But the call the the FORTRAN function was not there. There was the description of the camera object (properties and methods) not much help there.
So... back to Search "avCamera" and find the topic "Camera Property" which lists the FORTRAN call for avCamera. Technicaly speaking avCamera is not a property of a Camera object so what is this call doing under "Camera Property", never mind I got the call now....
Almost there. Dang!!! another reference to the opaque and ubiquitous "object"
Ding!.... round two.
Oops! Now I discover the documented call to avSetViewpoint doesn't match the interface statement in the library... So... I must figure out the call.
And so it goes. Over and over and over.
I almost gave up on AV after several rounds of this type of rope-a-dope activity.
From a new users point of view this was a horror show.
Now for the constructive part.
I strongly suggest that you place into the documentation an outline of the calls to the helper functions that obtain the object handles regardless of how redundant it may look in the documentation.
subroutine avSetViewpoint(object, vector, status)
integer(int_ptr_kind()), intent(IN) :: object
real(8), intent(IN) :: vector
integer, intent(OUT) :: status
end subroutine avSetViewpoint
Sample use:
Real(8) :: CameraXYZ(3)
...
hRoot = avGetObject("/")
...
call avCreateGraph3DObj(avGraphs(hRoot), "graph", hGraph)
...
call avSetViewpoint(avCamera(hGraph), CameraXYZ, iStat)
A few extracts of code would have cleared things up immensely.
From this example I can clearly see that "object" is a camera object obtained from a call to avCamera with a graph object which in turn was obtained when creating the graph. And the creation of the graph required a Graphs handle obtained from the graphs section of the root handle and the root handle which was obtained from a call to avGetObject.
Enough for the gripes.
I have found the AV library a powerful feature that could attract customers... But only if you can develop a user base. The biggest obstacle to developing a user base is poor documentation. Please put more effort into your documentation.
Jim Dempsey
Inventor
System and Method for Space Elevator
