SF_IOTOOLS

IOFILE submodule

Description

Contains procedures for generating output files

Quick access

Subroutines and functions

interface iofile/str(i4, npad, r8, c, bool, txt[, d, lead])

This function converts an integer, real, complex, logical or character variable into a character string, left-justified and without leading or trailing blanks. The specific procedures cover

an integer, optionally zero padded to Npad characters, str(12) gives 12 and str(12,5) gives 00012
a real, written in fixed format with d+lead decimals (defaults d=6, lead=1) if \(|r| \ge 10^{-lead}\), and in scientific format with d decimals otherwise, str(3.14159d0) gives 3.1415900
a complex, written as (re,im) with each part formatted as a real
a logical, written as T or F
a character string, stripped of leading and trailing blanks

Parameters:

i4 [integer] – integer to convert
npad [integer] – number of characters of the zero padded string
r8 [real] – real to convert
c [complex] – complex to convert
bool [logical] – logical to convert
txt [character(len=*)] – character string to strip of leading and trailing blanks

Result:

string [character(len=:), allocatable]

Options:

d [integer] – digits parameter of the format (default 6)
lead [integer] – values with abs < 10**(-lead) use scientific format (default 1)

interface iofile/txtfy(i4, npad, r8, c, bool, txt[, d, lead])

This function is obsolete, it is a synonym of str, with the same specific procedures.

Parameters:

i4 [integer] – integer to convert
npad [integer] – number of characters of the zero padded string
r8 [real] – real to convert
c [complex] – complex to convert
bool [logical] – logical to convert
txt [character(len=*)] – character string to strip of leading and trailing blanks

Result:

string [character(len=:), allocatable]

Options:

d [integer] – digits parameter of the format (default 6)
lead [integer] – values with abs < 10**(-lead) use scientific format (default 1)

interface iofile/reg(file)

This function removes the leading and trailing blanks of the character string file. The result has length len_trim(adjustl(file)).

Parameters:: file [character(len=*), in] – string whose leading and trailing blanks are removed
Result:: reg [character(len=len_trim(trim(adjustl(trim(file)))))]

interface iofile/create_dir(dir_name)

This subroutine creates the directory dir_name by calling the command mkdir -v. The parent directories are not created, and the error message of mkdir is printed if the directory can not be created, for example if it already exists.

Parameters:: dir_name [character(len=*)] – name of the directory to create

interface iofile/newunit()

This function returns a free unit number, see free_unit.

Result:: unit [integer]

interface iofile/print_matrix(m[, file, w, d])

This subroutine prints the real or complex matrix M row by row, on the standard output or in the file file if present. Each element is written with width w and d decimals, separated by a blank. Complex elements are written as (re,im). The file is opened with a unit given by free_unit, and it is not closed by the subroutine.

Parameters:

m (•, •) [real/complex] – matrix to print

Options:

file [character(len=*)] – file where to print the matrix (default: standard output)
w [integer] – width of each printed number (default 5)
d [integer] – number of decimals of each printed number (default 2)

function iofile/reverse(string[, n])

This function returns the last n characters of the character string string in reverse order, so the length of the result is n. If n is absent all the characters are reversed, hence reverse("abcdef") returns fedcba and reverse("abcdef",3) returns fed.

Parameters:: string [character(len=*), in] – string to reverse
Options:: n [integer, in] – number of characters to reverse, taken from the end of string (default len(string))
Result:: reverse_string [character(len=:), allocatable]

function iofile/get_filename(string)

This function returns the name of a file without its path, that is the part of string after the last /, without leading or trailing blanks. It is the whole string if it contains no /.

Parameters:: string [character(len=*)] – path of a file, directories separated by / character(len=len_trim(string)) :: fname
Result:: fname [character(len=:), allocatable]

function iofile/get_filepath(string)

This function returns the path of a file, that is the part of string up to and including the last /, without leading or trailing blanks. It is an empty string if string contains no /.

Parameters:: string [character(len=*)] – path of a file, directories separated by / character(len=len_trim(string)) :: pname
Result:: pname [character(len=:), allocatable]

function iofile/free_unit([n])

This function returns the lowest unit number larger than 100 that is not connected to a file, and stops the program if there is no free unit smaller than 900. If n is present it is set to the same value. The unit is not reserved, so it must be opened before the function is called again. The function is also available under the name newunit.

Options:: n [integer]
Result:: unit [integer]

function iofile/free_units(n)

This function returns an array of n different unit numbers larger than 100 that are not connected to a file at the time of the call. The program stops if no free unit smaller than 900 is found.

Parameters:: n [integer] – number of free units to return
Result:: unit (n) [integer]

function iofile/file_size(file[, printf])

This function returns the size in Kb of the file file, rounded to the nearest integer, obtained with the fstat system call. If the file does not exist a message is printed and the returned value is not set. If printf is true a message with the file name and its size is printed.

Parameters:: file [character(len=*)] – file name
Options:: printf [logical] – if T print the size of the file (default F)
Result:: size [integer]

function iofile/file_info(file)

This function prints on the screen the information on the file file returned by the fstat system call: device, inode, mode, number of links, owner and group ids, size, times, block size and number of blocks. It returns 0 if the file does not exist, otherwise the returned value is not set.

Parameters:: file [character(len=*)] – file name
Result:: file_info [integer]

function iofile/file_length(file[, verbose, incl_comments])

This function returns the number of lines of the file file. Blank lines, and comment lines, that is lines whose first item contains the character #, are not counted unless incl_comments is true, in which case only the blank lines are skipped. If the file does not exist but a compressed version with extension .gz, .bz2 or .xz does, the file is first uncompressed with file_gunzip, file_bunzip or file_unxz. If no file is found a message is printed and 0 is returned. If verbose is true, which is the default, the number of lines is printed.

Parameters:

file [character(len=*)] – file name, or name without extension of a .gz, .bz2 or .xz compressed file

Options:

verbose [logical] – if T print the number of lines (default T)
incl_comments [logical] – if T count the comment lines too (default F)

Result:

lines [integer]

subroutine iofile/set_store_size(size)

This subroutine sets the size size, in Kb, used as default threshold by file_gzip, file_bzip and file_xz: files that are not larger than this value are not compressed. The default is 2048 Kb. The new value is printed on the screen.

Parameters:: size [integer] – size threshold in Kb above which files are compressed (default 2048)

subroutine iofile/file_gzip(file[, size])

This subroutine compresses the file file with gzip -fv --best --rsyncable, producing file.gz, if its size given by file_size is larger than size Kb. The default threshold is the store size, 2048 Kb unless changed with set_store_size. Smaller files are left untouched.

Parameters:: file [character(len=*)] – file to compress
Options:: size [integer] – size threshold in Kb, smaller files are not compressed (default: store size)

subroutine iofile/file_gunzip(filename)

This subroutine uncompresses the file filename.gz with gunzip -fv, producing filename. Nothing is done if filename already exists. The program stops with a message if neither filename nor filename.gz exists.

Parameters:: filename [character(len=*)] – name of the uncompressed file, without the compression extension

subroutine iofile/file_bzip(file[, size])

This subroutine compresses the file file with bzip2 -zfv, producing file.bz2, if its size given by file_size is larger than size Kb. The default threshold is the store size, 2048 Kb unless changed with set_store_size. Smaller files are left untouched.

Parameters:: file [character(len=*)] – file to compress
Options:: size [integer] – size threshold in Kb, smaller files are not compressed (default: store size)

subroutine iofile/file_bunzip(filename)

This subroutine uncompresses the file filename.bz2 with bzip2 -dv, producing filename. Nothing is done if filename already exists. The program stops with a message if neither filename nor filename.bz2 exists.

Parameters:: filename [character(len=*)] – name of the uncompressed file, without the compression extension

subroutine iofile/file_xz(file[, size])

This subroutine compresses the file file with xz -zfv, producing file.xz, if its size given by file_size is larger than size Kb. The default threshold is the store size, 2048 Kb unless changed with set_store_size. Smaller files are left untouched.

Parameters:: file [character(len=*)] – file to compress
Options:: size [integer] – size threshold in Kb, smaller files are not compressed (default: store size)

subroutine iofile/file_unxz(filename)

This subroutine uncompresses the file filename.xz with xz -dv, producing filename. Nothing is done if filename already exists. The program stops with a message if neither filename nor filename.xz exists.

Parameters:: filename [character(len=*)] – name of the uncompressed file, without the compression extension

subroutine iofile/file_targz(tarball, pattern[, size])

This subroutine stores the files matching pattern in the compressed tarball tarball.tgz, created with tar -czf. If the command succeeds the archived files are removed with rm -f. The argument size is accepted for consistency with file_gzip but it is not used: the tarball is always written.

Parameters:

tarball [character(len=*)] – tarball name, without the .tgz or .tar.bz2 extension
pattern [character(len=*)] – files to archive, they are removed after a successful archive

Options:

size [integer] – not used

subroutine iofile/file_untargz(tarball)

This subroutine extracts the tarball tarball.tgz with tar -xzf, and removes it if the command succeeds. A message is printed and nothing is done if the tarball does not exist.

Parameters:: tarball [character(len=*)] – tarball name, without the .tgz or .tar.bz2 extension

subroutine iofile/file_tarbz2(tarball, pattern[, size])

This subroutine stores the files matching pattern in the bzip2 compressed tarball tarball.tar.bz2, created with tar -cjSf. If the command succeeds the archived files are removed with rm -f. The argument size is accepted for consistency with file_bzip but it is not used: the tarball is always written.

Parameters:

tarball [character(len=*)] – tarball name, without the .tgz or .tar.bz2 extension
pattern [character(len=*)] – files to archive, they are removed after a successful archive

Options:

size [integer] – not used

subroutine iofile/file_untarbz2(tarball)

This subroutine extracts the tarball tarball.tar.bz2 with tar -xjf, and removes it if the command succeeds. A message is printed and nothing is done if the tarball does not exist.

Parameters:: tarball [character(len=*)] – tarball name, without the .tgz or .tar.bz2 extension

function iofile/to_upper(strin)

This function returns the character string StrIn with the lower case letters a-z converted to upper case. The other characters are unchanged.

Parameters:: strin [character(len=*), in] – string to convert
Result:: strout [character(len=len(strin))]

function iofile/to_lower(strin)

This function returns the character string StrIn with the upper case letters A-Z converted to lower case. The other characters are unchanged.

Parameters:: strin [character(len=*), in] – string to convert
Result:: strout [character(len=len(strin))]

IOREAD submodule

Description

Contains procedures for reading files

Quick access

Routines:: read_array(), sread()

Used modules

iofile: Contains procedures for generating output files

Subroutines and functions

interface ioread/sread(pname, x, y1)

This subroutine reads a real or complex array of rank 1 to 7 from the file pname, together with the abscissa X, and is the counterpart of splot. The last dimension of Y1 runs along X, and each line of the file contains X(k) Y1(...,k) for a real array and X(k) Im Y1(...,k) Re Y1(...,k) for a complex array. The blank lines between the curves are skipped. If the file, or its .gz version, is not found a message is printed, the program waits 5 seconds, and then stops with an end-of-file error when reading.

Parameters:

pname [character(len=*)] – name of the input file
x (various shapes) [real, in,required]
y1 (various shapes) [real/complex]

interface ioread/read_array(pname, y1[, order, wspace])

This subroutine reads a real or complex scalar, or array of rank 1 to 7, Y1 from the file pname, and is the counterpart of save_array. If pname does not exist the file pname.bz2 is first uncompressed with file_bunzip, and after reading the file is compressed again with file_bzip if it is larger than the store size, see set_store_size. If the file, or its .gz version, is not found a message is printed, the program waits 5 seconds, and then stops with an end-of-file error when reading.

For rank 2 to 7 the order of the elements is set by order. With order="R" the last index varies fastest, with order="C" the first index varies fastest. The program stops if order does not start with R or C. The blank lines separating the runs are skipped, so wspace has no effect when reading.

Parameters:

pname [character(len=*)] – name of the input file
y1 (various shapes) [real/complex]

Options:

order [character(len=*)] – R (default): last index varies fastest, C: first index varies fastest
wspace [logical] – not used when reading, present for consistency with save_array

IOPLOT submodule

Quick access

Routines:: save_array(), splot(), splot3d()

Used modules

iofile: Contains procedures for generating output files

Subroutines and functions

interface ioplot/splot(pname, x, y1[, append])

This subroutine writes a real or complex array Y1 of rank 1 to 7 to the file pname, together with the abscissa X, in a format that can be plotted with gnuplot. The last dimension of Y1 runs along X. Each line of the file contains

X(k) Y1(...,k) for a real array
X(k) Im Y1(...,k) Re Y1(...,k) for a complex array, so the imaginary part is in column 2 and the real part in column 3

For rank 2 to 7 a blank line follows each set of size(X) lines, so that each one-dimensional slice is a separate curve. If append is true the data are added at the end of the file, after a blank line if the file already exists, otherwise an existing file is overwritten. The data can be read back with sread.

Parameters:

pname [character(len=*)] – name of the output file
x (various shapes) [real, in,required] – abscissa, one per element of the last dimension of Y1
y1 (various shapes) [real/complex] – function values Y1(…,k) at X(k), real or complex, rank 1 to 7

Options:

append [logical] – if T add to an existing file instead of overwriting it (default F)

interface ioplot/splot3d(pname, x1, x2, y[, xmin, xmax, ymin, ymax, nosurface, wlines, nlines])

This subroutine writes a function of two variables, given on the grid X1 \(\times\) X2, to files that can be plotted with gnuplot as a color map and as a surface. The specific procedures cover a real or complex array Y of shape (size(X1),size(X2)), and a real or complex sequence of Nt frames Y of shape (size(X1),size(X2),Nt) for an animated map.

For a real Y the data file pname contains the lines X1(i) X2(j) Y(i,j), with a blank line after each value of i. The gnuplot scripts pname_map.gp (color map) and, unless nosurface is true, pname_surface.gp (surface view) are written next to it. If wlines is present, whatever its value, the file pname_withlines is also written with every nlines-th value of i, to be plotted as lines over the surface.

For a complex Y the real and imaginary parts are written in the files re_name and im_name, in the directory of pname, with the scripts pname_re_map.gp, pname_im_map.gp, pname_re_surface.gp and pname_im_surface.gp.

The animate procedures write all the frames in the data file, one block per frame, and only the map script(s), which loop over the frames with a color range common to all of them. They stop if the first two dimensions of Y do not match X1 and X2. The plot ranges default to the extrema of X1 and X2, see xmin.

Parameters:

pname [character(len=*)] – name of the data file, base name of the gnuplot scripts
x1 (•) [real, in,required] – grid points along x, first dimension of Y
x2 (•) [real, in,required] – grid points along y, second dimension of Y
y (various shapes) [real/complex] – values Y(i,j)=F(X1(i),X2(j)); Y(i,j,m) for animate

Options:

xmin [real]
xmax [real]
ymin [real]
ymax [real] – plot ranges in x and y (default: extrema of X1, X2)
nosurface [logical] – if T do not write the gnuplot script of the surface (default F)
wlines [logical] – if present also write the _withlines file (any value)
nlines [integer] – step of the first index in the _withlines file (default 5)

interface ioplot/save_array(pname, y1[, order, wspace])

This subroutine writes a real or complex scalar, or array of rank 1 to 7, Y1 to the file pname using list-directed output, one element per line, complex elements as (re,im). After writing, the file is compressed with file_bzip if it is larger than the store size, see set_store_size.

For rank 2 to 7 the order of the elements is set by order. With order="R" the last index varies fastest, with order="C" the first index varies fastest. If wspace is true a blank line is written after each run of the fastest index. The program stops if order does not start with R or C. The data can be read back with read_array.

Parameters:

pname [character(len=*)] – name of the output file
y1 (various shapes) [real/complex] – data to write: scalar or array of rank 1 to 7, real or complex

Options:

order [character(len=*)] – R (default): last index varies fastest, C: first index varies fastest
wspace [logical] – if T (default) write a blank line after each run of the fastest index