Is there better documentation for the Fortran API?

[rhdtownsend]

I'm keen to use Caliper to instrument my Fortran codes; however, I'm having trouble finding the information I need in the main documentation site (https://software.llnl.gov/Caliper/index.html).

For instance, the Fortran demonstration given at https://software.llnl.gov/Caliper/FortranSupport.html shows how to annotate a loop:

    !   Annotate a loop. We'll have to find Caliper's built-in "loop"
    ! attribute first and create a loop iteration attribute, using the region
    ! name ("mainloop") of our loop.

    loop_attribute = cali_find_attribute('loop')
    iter_attribute = cali_make_loop_iteration_attribute('mainloop')

    call cali_begin_string(loop_attribute, 'mainloop')
    do i = 1, count
        call cali_begin_int(iter_attribute, i)

        ! ...

        call cali_end(iter_attribute)
    end do
    call cali_end(loop_attribute)

However, the pair of functions, cali_find_attribute() and cali_make_loop_iteration_attribute(), are not documented anywhere else. What does the 'mainloop' argument to the latter function do? Changing it to other values seems to have no effect to this code, and I therefore can't see how Caliper knows that iter_attribute 'belongs' to loop_attribute (in that iter_attribute counts the iterations of loop_attribute).

Also, how would one go about annotating a nested pair of loops? Do I need two separate loop and iter attributes? How do I avoid ending up with the same loop attribute when I call cali_find_attribute('loop') twice?

[daboehme]

Hi @rhdtownsend, unfortunately I don't have much more Fortran-specific documentation for Caliper aside from the Fortran support chapter and the example apps. However much of the general annotation API documentation also applies to Fortran, which simply wraps the C functions.

To answer your specific questions, the cali_find_attribute function retrieves an existing attribute key - the "loop" attribute here is a built-in attribute in Caliper to mark loop regions. The cali_make_loop_iteration_attribute function constructs a special attribute to mark loop iterations. The name parameter here should match the name of the corresponding loop region, e.g. "mainloop" in the example. The resulting iteration attribute will be then called iteration#mainloop.

To annotate nested loops you can simply add another loop region with a name like "inner loop" inside the main loop and create another iteration attribute for this loop. This should do it:

loop_attribute = cali_find_attribute('loop')
main_iter_attribute = cali_make_loop_iteration_attribute('mainloop')
inner_iter_attribute = cali_make_loop_iteration_attribute('inner loop')

call cali_begin_string(loop_attribute, 'mainloop')
do i = 1, count
    call cali_begin_int(main_iter_attribute, i)

    call cali_begin_string(loop_attribute, 'inner loop')
    do j = 1, count
        call cali_begin_int(inner_iter_attribute, j)
        ! ....
        call cali_end(inner_iter_attribute)
    end do
    call cali_end(loop_attribute)

    call cali_end(main_iter_attribute)
end do
call cali_end(loop_attribute)

Results will depend on the Caliper measurement recipe. If you record a trace you will see two iteration attributes for inner-loop regions, iteration#mainloop storing the main loop iteration and iteration#inner loop storing the inner loop iteration. The loop-report configuration only reports the outer loop by default, but you can switch it to the inner loop with the target_loops switch. A runtime-report will simply show both loops as nested regions, but you can get min/max/avg time per iteration statistics for both loops with the loop.stats option in Caliper v2.12 (i.e., runtime-report,loop.stats).

Note that the loop annotations are intended for high-level loops, I wouldn't recommend annotating tight inner loops as that could cause some overhead.

Hope this helps! Feel free to reach out if you have any further questions.

[rhdtownsend]

Thanks for this detailed reply, David -- and thanks also for your work on Caliper!

Rich