Merge pull request #800 from MilanSkocic/master

Addition of Codata constants

Author: jvdp1

doc/specs/index.md

@@ -14,6 +14,7 @@ This is an index/directory of the specifications (specs) for each new module/fea
  - [ansi](./stdlib_ansi.html) - Terminal color and style escape sequences
  - [array](./stdlib_array.html) - Procedures for index manipulation and array handling
  - [ascii](./stdlib_ascii.html) - Procedures for handling ASCII characters
+ - [constants](./stdlib_constants.html) - Constants
  - [bitsets](./stdlib_bitsets.html) - Bitset data types and procedures
  - [error](./stdlib_error.html) - Catching and handling errors
  - [hash](./stdlib_hash_procedures.html) - Hashing integer

doc/specs/stdlib_constants.md

@@ -0,0 +1,78 @@
+---
+title: constants
+---
+
+[TOC]
+
+## Introduction
+
+
+The [[stdlib_constants]] module provides mathematical constants and the most common physical constants.
+
+**Warning**: The names of the most common physical constants are kept short as they are inside a dedicated module. 
+Nonetheless, in case of overlapping names, they can always be renamed as following:
+
+```fortran
+use stdlib_constants, only: clight => c
+```
+
+## Codata
+
+The [[stdlib_codata(module)]] module defines all codata (physical) constants as derived 
+type. The module is automatically generated with a simple 
+[parser written in Python](https://github.com/MilanSkocic/codata/)
+The latest codata constants were released in 2022 by the [NIST](http://physics.nist.gov/constants)
+All values for the codata constants are provided as double precision reals. 
+The names are quite long and can be aliased with shorter names.
+
+The derived type [[stdlib_codata_type(module):codata_constant_type(type)]] defines:
+
+* 4 members:
+
+    * `name` (string)
+    * `value` (double precision real)
+    * `uncertainty` (double precision real)
+    * `unit` (string)
+
+* 2 type-bound procedures:
+
+    * `print`: to print the values of the constant members;
+    * `to_real`: to get the value or the uncertainty to the desired precision.
+
+A module level interface [[stdlib_codata_type(module):to_real(interface)]] is 
+available for getting the constant value or uncertainty of a constant. 
+
+## `to_real` - Get the constant value or its uncertainty.
+
+### Status
+
+Experimental
+
+### Description
+
+Convert a [[stdlib_codata_type(module):codata_constant_type(type)]] to a `real` (at least `sp`, or `dp`) scalar. 
+**Warning**: Some constants cannot be converted to single precision `sp` reals due to the value of the exponents.
+
+### Syntax
+
+`r = ` [[stdlib_codata_type(module):to_real(interface)]] `(c, mold [, uncertainty])`
+
+### Arguments
+
+`c`: argument has `intent(in) ` and shall be of type [[stdlib_codata_type(module):codata_constant_type(type)]].
+
+`mold`: argument has `intent(in)` and shall be of `real` type. 
+**Note**: The type of the `mold` argument defines the type of the result.
+
+`uncertainty` (optional): argument has `intent(in)` and shall be of `logical` type. 
+It specifies if the uncertainty needs to be returned instead of the value. Default to `.false.`.
+
+### Return value
+
+Returns a scalar of `real` type which is either the value or the uncertainty of a codata constant.
+
+## Example
+
+```fortran
+{!example/constants/example_constants.f90!}
+```

example/CMakeLists.txt

@@ -9,6 +9,7 @@ endmacro(ADD_EXAMPLE)
 add_subdirectory(array)
 add_subdirectory(ascii)
 add_subdirectory(bitsets)
+add_subdirectory(constants)
 add_subdirectory(error)
 add_subdirectory(hashmaps)
 add_subdirectory(hash_procedures)

example/constants/CMakeLists.txt

@@ -0,0 +1 @@
+ADD_EXAMPLE(constants)

example/constants/example_constants.f90

@@ -0,0 +1,25 @@
+program example_constants
+    use stdlib_constants, only: c, pi=>PI_dp
+    use stdlib_codata, only: alpha=>ALPHA_PARTICLE_ELECTRON_MASS_RATIO
+    use stdlib_codata_type, only : to_real
+    use stdlib_kinds, only: dp, sp
+
+    ! Use most common physical constants defined as double precision reals
+    print *, "speed of light in vacuum= ", c
+
+    ! Use of mathematical constants such as PI
+    print *, "PI as double precision real= ", pi
+
+    ! Use codata_constant type for evaluating the value to the desired precision
+    print *, "Value of alpha... evaluated to double precision=", alpha%to_real(1.0_dp)
+    print *, "Uncertainty of alpha... evaluated to double precision=", alpha%to_real(1.0_sp, .true.)
+    print *, "Value of alpha... evaluated to single precision=", alpha%to_real(1.0_sp)
+
+    ! Convert a codata constant to a real
+    print *, "Value of the alpha... evaluated to double precision=", to_real(alpha, 1.0_dp)
+
+
+    ! Print out codata constant attributes: name, value, uncertainty and unit
+    call alpha%print()
+
+end program example_constants

src/CMakeLists.txt

@@ -6,14 +6,16 @@ set(fppFiles
     stdlib_bitsets.fypp
     stdlib_bitsets_64.fypp
     stdlib_bitsets_large.fypp
-    stdlib_hash_32bit.fypp 
+    stdlib_codata_type.fypp
+    stdlib_constants.fypp
+    stdlib_hash_32bit.fypp
     stdlib_hash_32bit_fnv.fypp
-    stdlib_hash_32bit_nm.fypp 
-    stdlib_hash_32bit_water.fypp 
-    stdlib_hash_64bit.fypp 
-    stdlib_hash_64bit_fnv.fypp 
-    stdlib_hash_64bit_pengy.fypp 
-    stdlib_hash_64bit_spookyv2.fypp 
+    stdlib_hash_32bit_nm.fypp
+    stdlib_hash_32bit_water.fypp
+    stdlib_hash_64bit.fypp
+    stdlib_hash_64bit_fnv.fypp
+    stdlib_hash_64bit_pengy.fypp
+    stdlib_hash_64bit_spookyv2.fypp
     stdlib_io.fypp
     stdlib_io_npy.fypp
     stdlib_io_npy_load.fypp
@@ -25,9 +27,9 @@ set(fppFiles
     stdlib_linalg_outer_product.fypp
     stdlib_linalg_kronecker.fypp
     stdlib_linalg_cross_product.fypp
-    stdlib_linalg_solve.fypp    
+    stdlib_linalg_solve.fypp
     stdlib_linalg_determinant.fypp
-    stdlib_linalg_state.fypp 
+    stdlib_linalg_state.fypp
     stdlib_optval.fypp
     stdlib_selection.fypp
     stdlib_sorting.fypp
@@ -68,7 +70,7 @@ set(fppFiles
     stdlib_version.fypp
 )
 
-# Preprocessed files to contain preprocessor directives -> .F90 
+# Preprocessed files to contain preprocessor directives -> .F90
 set(cppFiles
     stdlib_linalg_constants.fypp
     stdlib_linalg_blas.fypp
@@ -97,6 +99,7 @@ set(SRC
     stdlib_ansi_operator.f90
     stdlib_ansi_to_string.f90
     stdlib_array.f90
+    stdlib_codata.f90
     stdlib_error.f90
     stdlib_hashmap_wrappers.f90
     stdlib_hashmaps.f90