PartMC  2.2.1
Public Member Functions | Public Attributes
pmc_util Module Reference

Common utility subroutines. More...

List of all members.

Public Member Functions

subroutine warn_msg (code, warning_msg)
 Prints a warning message.
subroutine warn_assert_msg (code, condition_ok, warning_msg)
 Prints a warning message if condition_ok is false.
subroutine assert_msg (code, condition_ok, error_msg)
 Errors unless condition_ok is true.
subroutine assert (code, condition_ok)
 Errors unless condition_ok is true.
subroutine die (code)
 Error immediately.
subroutine die_msg (code, error_msg)
 Error immediately.
integer function get_unit ()
 Returns an available unit number. This should be freed by free_unit().
subroutine free_unit (unit)
 Frees a unit number returned by get_unit().
subroutine open_file_read (filename, unit)
 Open a file for reading with an automatically assigned unit and test that it succeeds. The file should be closed with close_file().
subroutine open_file_write (filename, unit)
 Open a file for writing with an automatically assigned unit and test that it succeeds. The file should be closed with close_file().
subroutine close_file (unit)
 Close a file and de-assign the unit.
logical function almost_equal (d1, d2)
 Convert volume (m^3) to radius (m).
logical function almost_equal_abs (d1, d2, abs_tol)
 Tests whether two real numbers are almost equal using an absolute and relative tolerance.
subroutine check_time_multiple (first_name, first_time, second_name, second_time)
 Check that the first time interval is close to an integer multiple of the second, and warn if it is not.
subroutine check_event (time, timestep, interval, last_time, do_event)
 Computes whether an event is scheduled to take place.
subroutine linspace (min_x, max_x, x)
 Makes a linearly spaced array from min to max.
subroutine logspace (min_x, max_x, x)
 Makes a logarithmically spaced array of length n from min to max.
integer function linspace_find (min_x, max_x, n, x)
 Find the position of a real number in a 1D linear array.
integer function logspace_find (min_x, max_x, n, x)
 Find the position of a real number in a 1D logarithmic array.
integer function find_1d (n, x_vals, x)
 Find the position of a real number in an arbitrary 1D array.
real(kind=dp) function interp_1d (x_vals, y_vals, x)
 1D linear interpolation.
real(kind=dp) function interp_linear_disc (x_1, x_n, n, i)
 Linear interpolation over discrete indices.
integer function string_to_integer (string)
 Convert a string to an integer.
real(kind=dp) function string_to_real (string)
 Convert a string to a real.
logical function string_to_logical (string)
 Convert a string to a logical.
character(len=PMC_UTIL_CONVERT_STRING_LEN)
function 
integer_to_string (val)
 Convert an integer to a string format.
character(len=PMC_UTIL_CONVERT_STRING_LEN)
function 
real_to_string (val)
 Convert a real to a string format.
character(len=PMC_UTIL_CONVERT_STRING_LEN)
function 
logical_to_string (val)
 Convert a logical to a string format.
character(len=PMC_UTIL_CONVERT_STRING_LEN)
function 
complex_to_string (val)
 Convert a complex to a string format.
character(len=PMC_UTIL_CONVERT_STRING_LEN)
function 
integer_to_string_max_len (val, max_len)
 Convert an integer to a string format of maximum length.
character(len=PMC_UTIL_CONVERT_STRING_LEN)
function 
real_to_string_max_len (val, max_len)
 Convert a real to a string format of maximum length.
character(len=PMC_UTIL_CONVERT_STRING_LEN)
function 
time_to_string_max_len (time, max_len)
 Convert a time to a string format of maximum length.
subroutine vec_cts_to_disc (n, vec_cts, n_samp, vec_disc)
 Convert a real-valued vector into an integer-valued vector.
subroutine average_integer (int_vec, int_avg)
 Computes the average of an array of integer numbers.
subroutine average_real (real_vec, real_avg)
 Computes the average of an array of real numbers.
subroutine ensure_real_array_size (x, n)
 Reallocate the given array to ensure it is of the given size.
subroutine get_basename (filename, basename)
 Strip the extension to find the basename.
subroutine iso8601_date_and_time (date_time)
 Current date and time in ISO 8601 format.
real(kind=dp) function deg2rad (deg)
 Convert degrees to radians.
real(kind=dp) function rad2deg (rad)
 Convert radians to degrees.
subroutine integer_sort (data, perm)
 Sort the given data array and return the permutation defining the sort.
subroutine loadtxt (filename, data)
 Load a real array from a text file.
subroutine reallocate_real_array2d (data, rows, cols)
 Reallocate a 2D real array to the given size, preserving the contents.
subroutine read_char_raw (unit, char, eol, eof)
 Read a single character from a file, signaling if we have hit end-of-line (EOL) or end-of-file (EOF). If EOL or EOF are true then the character value should be ignored.
subroutine read_word_raw (unit, word, eol, eof)
 Read a white-space delimited word from a file, signaling if we have EOL or EOF. If EOL or EOF are true then the word will still be meaningful data. If there was no data to be read then len(word) will be 0.

Public Attributes

integer, parameter max_units = 200
 Maximum number of IO units usable simultaneously.
integer, parameter unit_offset = 10
 Minimum unit number to allocate.
logical, dimension(max_units), save unit_used = .false.
 Table of unit numbers storing allocation status.
integer, parameter PMC_UTIL_CONVERT_STRING_LEN = 100
 Length of string for converting numbers.
integer, parameter PMC_MAX_FILENAME_LEN = 300
 Maximum length of filenames.

Detailed Description

Common utility subroutines.

Definition at line 9 of file util.F90.


Member Function/Subroutine Documentation

logical function pmc_util::almost_equal ( real(kind=dp), intent(in)  d1,
real(kind=dp), intent(in)  d2 
)

Convert volume (m^3) to radius (m).

Volume (m^3). Convert volume (m^3) to diameter (m). Volume (m^3). Convert radius (m) to diameter (m). Radius (m). Convert radius (m) to volume (m^3). Radius (m). Convert diameter (m) to radius (m). Diameter (m). Convert diameter (m) to volume (m^3). Diameter (m). Tests whether two real numbers are almost equal using only a relative tolerance.

Parameters:
[in]d1First number to compare.
[in]d2Second number to compare.

Definition at line 304 of file util.F90.

logical function pmc_util::almost_equal_abs ( real(kind=dp), intent(in)  d1,
real(kind=dp), intent(in)  d2,
real(kind=dp), intent(in)  abs_tol 
)

Tests whether two real numbers are almost equal using an absolute and relative tolerance.

Parameters:
[in]d1First number to compare.
[in]d2Second number to compare.
[in]abs_tolTolerance for when d1 equals d2.

Definition at line 331 of file util.F90.

subroutine pmc_util::assert ( integer, intent(in)  code,
logical, intent(in)  condition_ok 
)

Errors unless condition_ok is true.

Parameters:
[in]codeStatus code to use if assertion fails.
[in]condition_okWhether the assertion is ok.

Definition at line 95 of file util.F90.

subroutine pmc_util::assert_msg ( integer, intent(in)  code,
logical, intent(in)  condition_ok,
character(len=*), intent(in)  error_msg 
)

Errors unless condition_ok is true.

Parameters:
[in]codeStatus code to use if assertion fails.
[in]condition_okWhether the assertion is ok.
[in]error_msgMsg if assertion fails.

Definition at line 69 of file util.F90.

subroutine pmc_util::average_integer ( integer, dimension(:), intent(in)  int_vec,
integer, intent(out)  int_avg 
)

Computes the average of an array of integer numbers.

Parameters:
[in]int_vecArray of integer numbers.
[out]int_avgAverage of int_vec.

Definition at line 960 of file util.F90.

subroutine pmc_util::average_real ( real(kind=dp), dimension(:), intent(in)  real_vec,
real(kind=dp), intent(out)  real_avg 
)

Computes the average of an array of real numbers.

Parameters:
[in]real_vecArray of real numbers.
[out]real_avgAverage of real_vec.

Definition at line 974 of file util.F90.

subroutine pmc_util::check_event ( real(kind=dp), intent(in)  time,
real(kind=dp), intent(in)  timestep,
real(kind=dp), intent(in)  interval,
real(kind=dp), intent(inout)  last_time,
logical, intent(out)  do_event 
)

Computes whether an event is scheduled to take place.

The events should occur ideally at times 0, interval, 2*interval, etc. The events are guaranteed to occur at least interval * (1 - tolerance) apart, and if at least interval time has passed then the next call is guaranteed to do the event. Otherwise the timestep is used to guess whether to do the event.

Parameters:
[in]timeCurrent time.
[in]timestepEstimate of the time to the next call.
[in]intervalHow often the event should be done.
[in,out]last_timeWhen the event was last done.
[out]do_eventWhether the event should be done.

Definition at line 389 of file util.F90.

subroutine pmc_util::check_time_multiple ( character(len=*), intent(in)  first_name,
real(kind=dp), intent(in)  first_time,
character(len=*), intent(in)  second_name,
real(kind=dp), intent(in)  second_time 
)

Check that the first time interval is close to an integer multiple of the second, and warn if it is not.

Parameters:
[in]first_nameName of the first time variable.
[in]first_timeFirst time variable (s).
[in]second_nameName of the second time variable.
[in]second_timeSecond time variable (s).

Definition at line 361 of file util.F90.

subroutine pmc_util::close_file ( integer, intent(in)  unit)

Close a file and de-assign the unit.

Parameters:
[in]unitUnit to close.

Definition at line 218 of file util.F90.

character(len=PMC_UTIL_CONVERT_STRING_LEN) function pmc_util::complex_to_string ( complex(kind=dc), intent(in)  val)

Convert a complex to a string format.

Parameters:
[in]valValue to convert.

Definition at line 784 of file util.F90.

real(kind=dp) function pmc_util::deg2rad ( real(kind=dp), intent(in)  deg)

Convert degrees to radians.

Parameters:
[in]degInput degrees.

Definition at line 1062 of file util.F90.

subroutine pmc_util::die ( integer, intent(in)  code)

Error immediately.

Parameters:
[in]codeStatus code to use if assertion fails.

Definition at line 114 of file util.F90.

subroutine pmc_util::die_msg ( integer, intent(in)  code,
character(len=*), intent(in)  error_msg 
)

Error immediately.

Parameters:
[in]codeStatus code to use if assertion fails.
[in]error_msgMsg if assertion fails.

Definition at line 126 of file util.F90.

subroutine pmc_util::ensure_real_array_size ( real(kind=dp), dimension(:), intent(inout), allocatable  x,
integer, intent(in)  n 
)

Reallocate the given array to ensure it is of the given size.

Parameters:
[in,out]xArray of real numbers.
[in]nDesired size of array.

Definition at line 988 of file util.F90.

integer function pmc_util::find_1d ( integer, intent(in)  n,
real(kind=dp), dimension(n), intent(in)  x_vals,
real(kind=dp), intent(in)  x 
)

Find the position of a real number in an arbitrary 1D array.

Takes an array of x_vals, and a single x value, and returns the position p such that x_vals(p) <= x < x_vals(p+1). If p == 0 then x < x_vals(1) and if p == n then x_vals(n) <= x. x_vals must be sorted in increasing order.

If the array is known to be linearly or logarithmically spaced then linspace_find() or logspace_find() will be much faster.

Parameters:
[in]nNumber of values.
[in]x_valsX value array, must be sorted.
[in]xValue to interpolate at.

Definition at line 565 of file util.F90.

subroutine pmc_util::free_unit ( integer, intent(in)  unit)

Frees a unit number returned by get_unit().

Definition at line 164 of file util.F90.

subroutine pmc_util::get_basename ( character(len=*), intent(in)  filename,
character(len=*), intent(out)  basename 
)

Strip the extension to find the basename.

The filename is assumed to be of the form basename.extension, where extension contains no periods. If there is no period in filename then basename is the whole filename.

Parameters:
[in]filenameFull filename.
[out]basenameBasename.

Definition at line 1009 of file util.F90.

integer function pmc_util::get_unit ( )

Returns an available unit number. This should be freed by free_unit().

Definition at line 140 of file util.F90.

subroutine pmc_util::integer_sort ( integer, dimension(:), intent(inout)  data,
integer, dimension(size(data)), intent(out)  perm 
)

Sort the given data array and return the permutation defining the sort.

If data is the original data array, new_data is the sorted value of data, and perm is the returned permutation, then new_data(i) = data(perm(i)).

Parameters:
[in,out]dataData array to sort, sorted on exit.
[out]permPermutation defining the sort: new_data(i) = data(perm(i)).

Definition at line 1116 of file util.F90.

character(len=PMC_UTIL_CONVERT_STRING_LEN) function pmc_util::integer_to_string ( integer, intent(in)  val)

Convert an integer to a string format.

Parameters:
[in]valValue to convert.

Definition at line 732 of file util.F90.

character(len=PMC_UTIL_CONVERT_STRING_LEN) function pmc_util::integer_to_string_max_len ( integer, intent(in)  val,
integer, intent(in)  max_len 
)

Convert an integer to a string format of maximum length.

Parameters:
[in]valValue to convert.
[in]max_lenMaximum length of resulting string.

Definition at line 801 of file util.F90.

real(kind=dp) function pmc_util::interp_1d ( real(kind=dp), dimension(:), intent(in)  x_vals,
real(kind=dp), dimension(size(x_vals)), intent(in)  y_vals,
real(kind=dp), intent(in)  x 
)

1D linear interpolation.

Takes an array of x and y, and a single x value, and returns the corresponding y using linear interpolation. x_vals must be sorted.

Parameters:
[in]x_valsX value array, must be sorted.
[in]y_valsY value array.
[in]xValue to interpolate at.

Definition at line 599 of file util.F90.

real(kind=dp) function pmc_util::interp_linear_disc ( real(kind=dp), intent(in)  x_1,
real(kind=dp), intent(in)  x_n,
integer, intent(in)  n,
integer, intent(in)  i 
)

Linear interpolation over discrete indices.

Takes real values x_1 and x_n and integers n and i and returns the linear interpolation so that x_1 is returned when i = 1 and x_n is returned when i = n.

Parameters:
[in]x_1Value of x when i = 1.
[in]x_nValue of x when i = n.
[in]nNumber of points to interpolate over.
[in]iIndex to interpolate at.

Definition at line 632 of file util.F90.

subroutine pmc_util::iso8601_date_and_time ( character(len=*), intent(out)  date_time)

Current date and time in ISO 8601 format.

Parameters:
[out]date_timeResult string.

Definition at line 1042 of file util.F90.

subroutine pmc_util::linspace ( real(kind=dp), intent(in)  min_x,
real(kind=dp), intent(in)  max_x,
real(kind=dp), dimension(:), intent(out)  x 
)

Makes a linearly spaced array from min to max.

Parameters:
[in]min_xMinimum array value.
[in]max_xMaximum array value.
[out]xArray.

Definition at line 443 of file util.F90.

integer function pmc_util::linspace_find ( real(kind=dp), intent(in)  min_x,
real(kind=dp), intent(in)  max_x,
integer, intent(in)  n,
real(kind=dp), intent(in)  x 
)

Find the position of a real number in a 1D linear array.

If xa is the array allocated by linspace(min_x, max_x, xa) then i = linspace_find(min_x, max_x, n, x) returns the index i satisfying xa(i) <= x < xa(i+1) for min_x <= x < max_x. If x >= max_x then i = n. If x < min_x then i = 0. Thus 0 <= i <= n. Here n is the length of xa.

This is equivalent to using find_1d() but much faster if the array is linear.

Parameters:
[in]min_xMinimum array value.
[in]max_xMaximum array value.
[in]nNumber of entries.
[in]xValue.

Definition at line 509 of file util.F90.

subroutine pmc_util::loadtxt ( character(len=*), intent(in)  filename,
real(kind=dp), dimension(:,:), intent(inout), allocatable  data 
)

Load a real array from a text file.

Parameters:
[in]filenameFilename to read from.
[in,out]dataArray to store data in.

Definition at line 1154 of file util.F90.

character(len=PMC_UTIL_CONVERT_STRING_LEN) function pmc_util::logical_to_string ( logical, intent(in)  val)

Convert a logical to a string format.

Parameters:
[in]valValue to convert.

Definition at line 764 of file util.F90.

subroutine pmc_util::logspace ( real(kind=dp), intent(in)  min_x,
real(kind=dp), intent(in)  max_x,
real(kind=dp), dimension(:), intent(out)  x 
)

Makes a logarithmically spaced array of length n from min to max.

Parameters:
[in]min_xMinimum array value.
[in]max_xMaximum array value.
[out]xArray.

Definition at line 471 of file util.F90.

integer function pmc_util::logspace_find ( real(kind=dp), intent(in)  min_x,
real(kind=dp), intent(in)  max_x,
integer, intent(in)  n,
real(kind=dp), intent(in)  x 
)

Find the position of a real number in a 1D logarithmic array.

If xa is the array allocated by logspace(min_x, max_x, xa) then i = logspace_find(min_x, max_x, n, x) returns the index i satisfying xa(i) <= x < xa(i+1) for min_x <= x < max_x. If x >= max_x then i = n. If x < min_x then i = 0. Thus 0 <= i <= n. Here n is the length of xa.

This is equivalent to using find_1d() but much faster if the array is logarithmic.

Parameters:
[in]min_xMinimum array value.
[in]max_xMaximum array value.
[in]nNumber of entries.
[in]xValue.

Definition at line 539 of file util.F90.

subroutine pmc_util::open_file_read ( character(len=*), intent(in)  filename,
integer, intent(out)  unit 
)

Open a file for reading with an automatically assigned unit and test that it succeeds. The file should be closed with close_file().

Parameters:
[in]filenameFilename to open.
[out]unitUnit assigned to file.

Definition at line 177 of file util.F90.

subroutine pmc_util::open_file_write ( character(len=*), intent(in)  filename,
integer, intent(out)  unit 
)

Open a file for writing with an automatically assigned unit and test that it succeeds. The file should be closed with close_file().

Parameters:
[in]filenameFilename to open.
[out]unitUnit assigned to file.

Definition at line 198 of file util.F90.

real(kind=dp) function pmc_util::rad2deg ( real(kind=dp), intent(in)  rad)

Convert radians to degrees.

Parameters:
[in]radInput radians.

Definition at line 1074 of file util.F90.

subroutine pmc_util::read_char_raw ( integer, intent(in)  unit,
character, intent(out)  char,
logical, intent(out)  eol,
logical, intent(out)  eof 
)

Read a single character from a file, signaling if we have hit end-of-line (EOL) or end-of-file (EOF). If EOL or EOF are true then the character value should be ignored.

Testing with gfortran 4.5.3 and different length files shows:

Empty file (total file length 0): * eol = .false., eof = .true. * subsequent calls error

File containing a single 'A' character (total file length 1): * char = 'A', eol = .false., eof = .false. * eol = .false., eof = .true. * subsequent calls error

File containing a single newline '
' (total file length 1): * eol = .true., eof = .false. * eol = .false., eof = .true. * subsequent calls error

File containing a character and newline 'A
' (total file length 2): * char = 'A', eol = .false., eof = .false. * eol = .true., eof = .false. * eol = .false., eof = .true. * subsequent calls error

Parameters:
[in]unitUnit number to read from.
[out]charCharacter read.
[out]eolTrue if at EOL (end of line).
[out]eofTrue if at EOF (end of file).

Definition at line 1266 of file util.F90.

subroutine pmc_util::read_word_raw ( integer, intent(in)  unit,
character(len=*), intent(out)  word,
logical, intent(out)  eol,
logical, intent(out)  eof 
)

Read a white-space delimited word from a file, signaling if we have EOL or EOF. If EOL or EOF are true then the word will still be meaningful data. If there was no data to be read then len(word) will be 0.

Parameters:
[in]unitUnit number to read from.
[out]wordWord read.
[out]eolTrue if at EOL (end of line).
[out]eofTrue if at EOF (end of file).

Definition at line 1310 of file util.F90.

character(len=PMC_UTIL_CONVERT_STRING_LEN) function pmc_util::real_to_string ( real(kind=dp), intent(in)  val)

Convert a real to a string format.

Parameters:
[in]valValue to convert.

Definition at line 748 of file util.F90.

character(len=PMC_UTIL_CONVERT_STRING_LEN) function pmc_util::real_to_string_max_len ( real(kind=dp), intent(in)  val,
integer, intent(in)  max_len 
)

Convert a real to a string format of maximum length.

Parameters:
[in]valValue to convert.
[in]max_lenMaximum length of resulting string.

Definition at line 822 of file util.F90.

subroutine pmc_util::reallocate_real_array2d ( real(kind=dp), dimension(:,:), intent(inout), allocatable  data,
integer, intent(in)  rows,
integer, intent(in)  cols 
)

Reallocate a 2D real array to the given size, preserving the contents.

Parameters:
[in,out]dataArray to reallocate.
[in]rowsNew leading dimension.
[in]colsNew trailing dimension.

Definition at line 1218 of file util.F90.

integer function pmc_util::string_to_integer ( character(len=*), intent(in)  string)

Convert a string to an integer.

Parameters:
[in]stringString to convert.

Definition at line 653 of file util.F90.

logical function pmc_util::string_to_logical ( character(len=*), intent(in)  string)

Convert a string to a logical.

Parameters:
[in]stringString to convert.

Definition at line 698 of file util.F90.

real(kind=dp) function pmc_util::string_to_real ( character(len=*), intent(in)  string)

Convert a string to a real.

Parameters:
[in]stringString to convert.

Definition at line 676 of file util.F90.

character(len=PMC_UTIL_CONVERT_STRING_LEN) function pmc_util::time_to_string_max_len ( real(kind=dp), intent(in)  time,
integer, intent(in)  max_len 
)

Convert a time to a string format of maximum length.

Parameters:
[in]timeTime to convert (s).
[in]max_lenMaximum length of resulting string.

Definition at line 877 of file util.F90.

subroutine pmc_util::vec_cts_to_disc ( integer, intent(in)  n,
real(kind=dp), dimension(n), intent(in)  vec_cts,
integer, intent(in)  n_samp,
integer, dimension(n), intent(out)  vec_disc 
)

Convert a real-valued vector into an integer-valued vector.

Use n_samp samples. Returns discrete vector whose relative entry sizes are $ \ell_1 $ closest to the continuous vector.

Parameters:
[in]nNumber of entries in vectors.
[in]vec_ctsContinuous vector.
[in]n_sampNumber of discrete samples to use.
[out]vec_discDiscretized vector.

Definition at line 919 of file util.F90.

subroutine pmc_util::warn_assert_msg ( integer, intent(in)  code,
logical, intent(in)  condition_ok,
character(len=*), intent(in)  warning_msg 
)

Prints a warning message if condition_ok is false.

Parameters:
[in]codeStatus code to use.
[in]condition_okWhether the assertion is ok.
[in]warning_msgMessage to display.

Definition at line 51 of file util.F90.

subroutine pmc_util::warn_msg ( integer, intent(in)  code,
character(len=*), intent(in)  warning_msg 
)

Prints a warning message.

Parameters:
[in]codeStatus code to use.
[in]warning_msgMessage to display.

Definition at line 36 of file util.F90.


Member Data Documentation

integer, parameter pmc_util::max_units = 200

Maximum number of IO units usable simultaneously.

Definition at line 20 of file util.F90.

integer, parameter pmc_util::PMC_MAX_FILENAME_LEN = 300

Maximum length of filenames.

Definition at line 29 of file util.F90.

integer, parameter pmc_util::PMC_UTIL_CONVERT_STRING_LEN = 100

Length of string for converting numbers.

Definition at line 27 of file util.F90.

integer, parameter pmc_util::unit_offset = 10

Minimum unit number to allocate.

Definition at line 22 of file util.F90.

logical, dimension(max_units), save pmc_util::unit_used = .false.

Table of unit numbers storing allocation status.

Definition at line 24 of file util.F90.


The documentation for this module was generated from the following file: