Batteries Included Fortran Library (BiF-lib)

November 13, 2024 · View on GitHub

-

Batteries_Included

Batteries Included Fortran Library (BiF-lib)

Fortran library source files that assist in file I/O, common operations that are present in other languages, and include data types that mimic python data types (such as, list and dict).

 

USGS Software Websites

 

 

Important Updates

CHANGELOG.md for bug fixes, new features, and updates.

Direct download

  • if you have git installed you can obtain the full repository with:
    git clone https://code.usgs.gov/fortran/bif.git

Code Citation

Boyce, S.E., 2024, Batteries Included Fortran Library (BiF-lib), version 1.2: U.S. Geological Survey Software Release, https://doi.org/10.5066/P9K2IQ6Y

Additional Citations

Part of these utilities were developed for the following project:

  • Boyce, S.E., 2024, MODFLOW One-Water Hydrologic Flow Model (MF-OWHM) Conjunctive Use and Integrated Hydrologic Flow Modeling Software, version 2.x: U.S. Geological Survey Software Release, https://doi.org/10.5066/P9P8I8GS

  • Boyce, S.E., Hanson, R.T., Ferguson, I., Schmid, W., Henson, W., Reimann, T., Mehl, S.M., and Earll, M.M., 2020, One-Water Hydrologic Flow Model: A MODFLOW based conjunctive-use simulation software: U.S. Geological Survey Techniques and Methods 6–A60, 435 p., https://doi.org/10.3133/tm6A60

References

When appropriate, the source files include references to the algorithms used in the code.

This section highlights important publications that are used in this library.

The random number generation were based on algorithms described in:

The exponential and normal distribution random number generation were based on algorithms described in:

  • Marsaglia G, Tsang WW., 2000, The ziggurat method for generating random variables. Journal of Statistical Software. 2000; 5(8):1–7.
  • Doornik, JA., 2005, An improved ziggurat method to generate normal random samples. University of Oxford; 2005.
  • McFarland, C. D., 2016, A modified ziggurat algorithm for generating exponentially and normally distributed pseudorandom numbers. Journal of statistical computation and simulation, 86(7), 1281-1294.

The sorting methods were based on algorithms described in:

The Unicode UTF-8 code was written following the specification described in:

"Chapter 2. General Structure". The Unicode Standard(6.0 ed.). Mountain View, California, US: The Unicode Consortium. ISBN 978-1-936213-01-6.

Let Us Know What You Are Up To

If you have questions and comments feel free to contact the developers.

Also share any publications that involve the Batteries Included Fortran Library so we can add them to our publication list.

Notes About Repository

Markdown Files (.md)

Markdown (.md) files are placed throughout the repository to assist with informing about different repo aspects or provide general information. Markdown files are simple text files with some additional formatting for fast rendering in html.

Opening a markdown file in a text editor is human readable, but contains additional markdown syntax. If you search for Markdown viewers you can find a number of tools that will render the final formatting of the .md files.

For more information on markdown viewers, please read the readme.txt file.

Executive Summary

Standard Fortran provides limited data type, function, and subroutine support leaving the developer to write custom code for every project. This has lead to every developer having their own internal, homemade, Fortran library for doing common operations. In recognition of this, most newer programming languages incorporate a large set of standard data types and functions that the developer can use and reference. For example, the Python language developers called it a "Batteries Included" language because the python standard library includes advanced data types, including sets, lists, and dictionaries (hash tables) and common functions, such as random number generation and fast sorting of data. This Fortran library seeks to emulate many of the advanced features that are a standard part of newer programming languages--hence its name Batteries Included Fortran (BiF). As of now, it is not a complete standard library, but includes many valuable routines for assisting in developing code for numerical models.

The BiF source code is broken into a series of files, each containing a module with a specific theme. That theme is either to provide a generic function interface to a series of routines or data type design (fortran object). An example of an interface is the NUM2STR function that converts a Fortran base type into as string and is interfaced to the a set of hidden functions, that includes INT32_2STR, INT32_VEC2STR, INT64_2STR, INT64_VEC2STR, REL64_2STR, INT64_VEC2STR, TF_2STR_FMT, and others. An example of a data type design is the DATE_OPERATOR type, which can store time and date information and has a set of functions (methods) attached to the type that allow for common date, time, and calendar operations.

To make the source code, and the modules they contain, easier to understand the majority of the names are appended with::

  • _interface
    • To indicates source code contains a generic INTERFACE call for a set of subroutines for a specific task.
  • _instruction
    • To indicates source code defines one or more Derived Data Types definitions (Fortran Objects) and their associated methods (subroutines and functions associated with the object).

[[TOC]]

Source File Description and Compilation Order

The following table provides all the files in the src directory. They are grouped by the folders they reside in, which also identify the common theme among the source files.

The dependency order is set up such that a file with a higher dependency requires at least one file of a lower dependency order. For example, date_operator_instruction.f90 has a dependency order of 2, so it is dependent on at least one file that is of order 1 or 0. In this case, date_operator_instruction.f90 is dependent on calendar_functions.f90, which has an order number of 1.

For an exact listing of each files dependencies, please see open the file src_dependency_tree.md or src_dependency_tree.xlsx.

GroupNameDescriptionOrder
datetimecalendar_functions.f90Basic date, time, and calendar functions.1
datetimedate_operator_instruction.f90Date and time operations2
datetimesleep_interface.f90Function that pauses execution for the requested number of seconds.1
datetimetime_series_file_instruction.f90Defines time series type for reading a file that contains a time stamp and associated datum.8
datetimetimer_instruction.f90Basic timing data type1
dynamic_arraysdynamic_array.f90Wrapper for the dynamic_array_xyz modules2
dynamic_arraysdynamic_array_int32.f90Dynamic allocation array container type for integer(int32) type1
errorerror_interface.f90Error and warning routines2
errorwarning_type_instruction.f90Data type for reporting warnings and errors3
input_readerbuffered_reader_instruction.f90Preloads a file into a buffer for faster reading. Includes methods for reading from buffer.2
input_readergeneric_block_reader_instruction.f90Loads lines of text as a linked list for processing latter.
Automatically checks for BEGIN/END clauses for nested loading.		7
input_readerlist_array_input_interface.f90List-Array Input (LAI) routines that can automatically load data that is either STATIC or TRANSIENT and LIST or ARRAY.11
input_readersub_block_input_interface.f90Read multiple block style input that are specified by a transient file reader.11
input_readertransient_file_reader_instruction.f90Instruction on how to process and load Transient File Reader input.10
input_readeruload_and_sfac_interface.f90Universal loading and scale factor routines that can automatically load scalar, vector, and array data.9
iocycling_text_file_interface.f90Open WRITE-only, STREAM, UNFORMATTED file that is meant to be overwritten frequently
That is, it cycles through one write, then rewinds to the start of the file, then writes a new record.		6
iofile_incrementer_interface.f90Can increment file name with a number to the file name.4
iofile_info_interface.f90Queries a file by name or unit number; stores in a data type all Fortran properties about the file.1
iofile_io_interface.f90File name and unit operations4
iogeneric_input_file_instruction.f90Open a READ-only file based on keywords.6
iogeneric_open_interface.fppSpecifies options to open a file. Requires Fortran Pre-Processing.3
iogeneric_output_file_instruction.f90Open a WRITE-only file based on keywords.6
iopost_key_sub.f90Parse string to get specified post-keywords for file-io
Used by GenericInput and GenericOut		2
iosimple_file_io.f90Set of convenience routines for parsing input files and opening read only or write only files.
Uses code already defined in BiF; only use when minimal dependencies are required.		1
iowrite_array_interface.f90Write a 1D or 2D array to a file.2
math_numbersbinomial_interface.f90Calculates the binomial coefficient, C(n, k), for a given n and k.1
math_numbersdescriptive_statistics.f90Provides an routines for calculating basic descriptive statistics (eg mean, variance, etc).
Includes a data type for online estimation of the descriptive statistics		1
math_numbersfactorial_interface.f90Calculate the factorial for a given non-negative integer or real.1
math_numbersEquationParser.f90Parse string to solve an equation for a given variable set.3
math_numbershexadecimal_instruction.f90Provides hexadecimal structure with basic operations, such as addition and conversion to Unicode point.1
math_numbersisqrt_interface.f90Floor square root of integer using bisection method.1
math_numberslog2_interface.f90Log2 functions1
math_numbersnumber_conversion_interface.f90Convert numbers between decimal, binary, and hexadecimal bases and hexadecimal bytes.
Binary and hexadecimal numbers are stored as strings.		1
math_numberspower_interface.f90Provides optimized routines for solving 10^x
and a function that returns the closest power of 2 to provided number		1
math_numbersprime_finder.f90Functions that return the next largest prime number
or check if a number is prime.		1
math_numbersrandom_routines_interface.f90Random number generation routines for uniform, exponential, and normal distribution.
Can also shift values within a vector to randomize the order.		1
math_numbersrelax_interface.f90Relax and Dampening routines1
math_numberssecant_interface.f90Given a user supplied function solves for the root via the secant and bisection methods.1
sortsort_interface_ascii.f90Sorting 1D and 2D character data in ASCII, Case-less, or natural order.2
sortsort_interface_driver.f90Main driver module for sorting 1D and 2D data using one of four different sort methods.2
sortsort_interface_int32.f90Sorting 1D and 2D integer(Int32) data2
sortsort_interface_int64.f90Sorting 1D and 2D integer(Int64) data2
sortsort_interface_multi.f90Sorting multiple 1D arrays together as if they are a 2D array.
Each 1D array can be a different base type (such as Integer and Real).		2
sortsort_interface_rel32.f90Sorting 1D and 2D real(real32) data2
sortsort_interface_rel64.f90Sorting 1D and 2D real(real64) data2
sortsort_interface_wild.f90Generic sort interface that can sort any kind of 1D data by using a user-defined LESS and SWAP functions.
This allows sorting of custom data types or data groups.		2
spatialadjacency_list_instruction_and_shortest_path.f90Adjacency List Type that supports shortest path searches via the Dijkstra algorithm.4
spatialobs_group_interpolator.f90Observation point interpolation algorithms for cartesian space.3
spatialxy_grid_coordinate_interface.f90Rectangular cartesian coordinate system for structured grids.1
stringscast_to_string_interface.f90Interface that converts the byte representation of any variable to a string.
This is equivalent to reading a record written to a STREAM UNFORMATTED file with a CHARACTER type.		1
stringsis_ascii_interface.f90Check if string contains only ASCII characters.3
stringsline_writer_interface.f90Write to a buffered line text at specified positions.2
stringsnum2str_interface.f90Convert any INT, SNG, DBL, and Logical to a pretty formatted string1
stringsparse_word_interface.f90Parse string to next word separated by space, tab, and comma1
stringsstring_routines.f90String manipulation functions and GET_ routines.
GET_xyz routines covert string ABC to another string or data type xyz.		5
systemconsole_commander.f90Provides access to writing to command prompt with backspace for updating1
systemdirectory_iso_c_binding.f90Provides functions to change current directory, make a directory, and get the current path.
Can also determine if OS is Windows_NT or not.		1
systempath_interface.f90Creates missing directories in a path. Performs slash and back-slash operations2
systemsystem_call.f90Execute a command using the operating system shell and return the output from the command.1
types_and_containersarray_data_types_instruction.f90Data type that provide easy array access1
types_and_containersbinary_heap_instruction.f90Binary heap data type and sorting algorithm1
types_and_containerscircular_queue_instruction.f90Circular queue, which is a linked list that has the end of the list point to the start.1
types_and_containershash_table_instruction.f90Hash table data type that mimics a python dictionary to store all the Fortran base types.2
types_and_containersinteger_array_builder.f90Simple auto-allocation integer array for appending.1
types_and_containersinteger_queue_instruction.f90Simple push/pull linked list que1
types_and_containersIXJ_instruction.f90Data structure that reads and stores a list of data structured as a set of integers (I), then numbers (X), and then integers (J).8
types_and_containerslinked_list_instruction.f90Linked List Data Type base, INT, and CHAR1
types_and_containerslookup_table_instruction.f90Defines lookup table data type for reading sets of lookup tables and querying them.8
types_and_containersname_id_interface.f90Data type for associating a name with a model grid coordinate and value1
types_and_containersrolling_pointer_instruction.f90Pointer array for int32 or int64 that is useful for keeping track of past values or fast shifting of values by pointer re-assignment.1
types_and_containersvariable_pointer_list_interface.f90Contains array of pointers designed for collecting a different variable targets into one type.1
unicodeunicode_interface.f90Functions for parsing unicode strings or returning a unicode character for a given code point.1
unit_testunit_testing_instruction.f90Data type that provides unit test methods, such as assert.
Provides bookkeeping of what tests fail and pass.		1
util_miscalloc_interface.f90Allocate arrays with lots of options1
util_miscconstants.f90Defines a set of parameter variables that are used by the rest of the library.0
util_miscis_integer_interface.f90Function that determines if a variable contains an integer or not.1
util_miscis_routine_interface.f90IS_ query functions.
For example, IS_ODD returns if the number is odd.		1
util_miscposition_interface.f90Return index where a value is in a vector2
util_miscsame_memory_address_interface.f90Routine that tests if two variables occupy the same ram-memory location.1
util_miscset_array_interface.f90Fast setting arrays to a value, zero, or NaN1
util_miscutil_interface.f90Simple utility routines for processing numbers
(eg, near_zero and vec_adjust_maxsum) that were not large enough to standalone in a file.		2

Publications Involving BiF-lib

Basic Documentation and Code Publications

Boyce, S.E., Hanson, R.T., Ferguson, I., Schmid, W., Henson, W., Reimann, T., Mehl, S.M., and Earll, M.M., 2020, One-Water Hydrologic Flow Model: A MODFLOW based conjunctive-use simulation software: U.S. Geological Survey Techniques and Methods 6–A60, 435 p., https://doi.org/10.3133/tm6A60

Application Bibliography

Alattar, M., Troy, T., Russo, T. and Boyce, S. E., 2020, Modeling the surface water and groundwater budgets of the US using MODFLOW-OWHM. Advances in Water Resources, 143, p. 103682, https://doi.org/10.1016/j.advwatres.2020.103682

Boyce, S.E., and Yeh, W.G., 2014, Parameter-independent model reduction of transient groundwater flow models: Application to inverse problems, Advances in Water Resources, 69, pp. 168–180, http://dx.doi.org/10.1016/j.advwatres.2014.04.009

Boyce, S.E., Nishikawa, T., and Yeh, W.G., 2015, Reduced order modeling of the Newton formulation of MODFLOW to solve unconfined groundwater flow: Advances in Water Resources, 83, pp. 250-262. http://dx.doi.org/10.1016/j.advwatres.2015.06.005

Boyce, S.E., 2015, Model Reduction via Proper Orthogonal Decomposition of Transient Confined and Unconfined Groundwater-Flow: PhD Dissertation, Dept. of Civil Engineering, University of California at Los Angeles, 64p.

Hanson, R.T., Traum J., Boyce, S.E., Schmid, W., Hughes, J.D, W. W. G., 2015, Examples of Deformation-Dependent Flow Simulations of Conjunctive Use with MF-OWHM. Ninth International Symposium on Land Subsidence (NISOLS), Nagoya, Japan, 6p.

Hanson, R.T., Ritchie, A.B., Boyce, S.E., Galanter, A.E., Ferguson, I.A., Flint, L.E., and Henson, W.R., 2020, Rio Grande transboundary integrated hydrologic model and water-availability analysis, New Mexico and Texas, United States, and Northern Chihuahua, Mexico: U.S Geological Survey Scientific Investigations Report 2020–xxxx, xxx p.

Henson, W., Hanson, R.T., Boyce, S.E., 2020 (in press), Integrated Hydrologic model of the Salinas Valley, Monterey County, California: U.S Geological Survey Scientific Investigations Report 2020–xxxx, xxx p.

Rossetto, R., De Filippis, G., Triana, F., Ghetta, M., Borsi, I., Schmid, Wolfgang, 2019, Software tools for management of conjunctive use of surface- and groundwater in the rural environment: integration of the Farm Process and the Crop Growth Module in the FREEWAT platform: Agricultural Water Management, Vol 223, No. 105717, 18p. (https://doi.org/10.1016/j.agwat.2019.105717)

Russo, T.A, 2012, Hydrologic System Response to Environmental Change: Three Case Studies in California, PhD Dissertation, Department of Earth Sciences, University of California at Santa Cruz, 56p.

Russo, T.A, Fisher, A.T., and Lockwood, B.S., 2014, Assessment of Managed Aquifer Recharge Site Suitability Using a GIS and Modeling, Ground Water, pp.1-12, doi: 10.1111/gwat.12213

Disclaimer

Although the software has been subjected to rigorous review, it represents a specific compilation for the source code presented in https://code.usgs.gov/fortran/bif using the commit with the same version number (either release/stable or beta/experimental version).

Binary versions may not contain bug fixes that are applied to high version number. Generally the highest available version number will contain the most up to date set of bug fixes, features, and had the most historical code review. Lower version binaries are kept on this repository to have a historical record and easy access to compiled binaries used in the past.

The USGS reserves the right to update the software as needed pursuant to further analysis and review. No warranty, expressed or implied, is made by the USGS or the U.S. Government as to the functionality of the software and related material nor shall the fact of release constitute any such warranty. Furthermore, the software is released on condition that neither the USGS nor the U.S. Government shall be held liable for any damages resulting from its authorized or unauthorized use.