-
Notifications
You must be signed in to change notification settings - Fork 4
Interoperability Support
Usually interoperability refers to using parts of other libraries or code bases in your project. As used in Fortpy, it means being able to use previous versions of your own code within your own code! Depending on how much changes between major versions of your code, you may find that older files are no longer compatible. Here are some common scenarios that Fortpy helps patch up:
- You use plain-text input files for Fortran. The parameter values appear in a specific order and you haven't used keywords in the past; the order the lines come in determines what they mean. Between versions the order in the file changes. Now older files have parameters in the wrong place, or don't specify values for some new parameters. People who use your code have to manually edit each of the input files to change the order or add the new values in.
- A previous version of the code created output files with a different number of columns. The new code outputs additional information. However, you expect that the new code should still produce the results that the old code could (supposing they were valid). Since the output file structure changed, you can't just use a diff anymore to see if the files are the same.
Fortpy provides scripts and classes that use templates to convert files between versions of your code. You write a template for the input and output files in XML that specifies which lines belong to each version of the file. Lines that are common to multiple versions can be tagged as such. Using these templates, Fortpy can convert plain-text output files between versions. It can also convert input files from XML to plain text.
The idea behind only being able to convert XML input files to plain text is that XML is easier to maintain, allows keywords to be used for parameter values, can have tags appear in any order and is easier read by a human. If you allow your input files to be XML based, they can be edited more easily and the learning curve for the code is slightly lower. You can persuade people who use your code to switch to XML input files. Fortpy will convert old plain text files into XML for them.
Once you have switched to XML input files, you merely need to call a python script to launch your executable (instead of calling just the executable). The python scripts will convert any XML input files in the execution folder into the current plain text version for your code; once all the XML input files are converted, it can call the executable to run the code. Since Fortran doesn't deal well with XML files by itself, Fortpy acts as an interpreter between the XML files and your code.
The templates for output files are explained in great detail as part of the unit testing package. Here we describe the format for the XML input file templates.
You can convert input and output files to different formats using ./fortpy/scripts/convert.py, a script included in the Fortpy distribution. The script uses the argparse package for python for supporting command-line arguments. Since the arguments are documented well within the script, you can just call ./convert.py -h to get a full help screen on how to use the script. You can also peruse the script itself.