diff --git a/Web/coolprop/Configuration.rst b/Web/coolprop/Configuration.rst new file mode 100644 index 00000000..fe471772 --- /dev/null +++ b/Web/coolprop/Configuration.rst @@ -0,0 +1,30 @@ +.. _configuration: + +*********************** +Configuration Variables +*********************** + +At runtime, there are a several configuration variables that can be used to change the behavior of CoolProp + +.. warning:: The adjustment of the internal configuration variables might have side effects that you are not expecting, use with caution!! + +From C++ and the SWIG wrappers, the values can be directly set/changed by using the type-specified getter/setter functions :cpapi:`get_config_bool`, :cpapi:`set_config_bool`,:cpapi:`get_config_string`, :cpapi:`set_config_string`, etc. + +From all languages, the configuration state can obtained by retrieving the configuration state in the form of a JSON ( `http://json.org/`_ ) formatted string. For instance, in python, you can get the default configuration state from + +.. ipython:: + + In [0]: import CoolProp.CoolProp as CP, json + + In [0]: jj = json.loads(CP.get_config_as_json_string()) + + In [0]: json.dumps(jj, indent=2) + +Most modern languages have facilities for interfacing with JSON formatted strings and converting them back and forth with language-specific data structures. For instance, in python, there is the built-in ``json`` package that converts json-formatted strings to python dictionaries, lists, etc. + +Configuration Keys +------------------ + +Here is a list of (alphabetically sorted) configuration keys that can be used, along with a short description of the use of each of the configuration keys: + +.. include :: configuration_keys.rst.in \ No newline at end of file diff --git a/Web/coolprop/index.rst b/Web/coolprop/index.rst index b6230bb2..352f26ab 100644 --- a/Web/coolprop/index.rst +++ b/Web/coolprop/index.rst @@ -11,4 +11,5 @@ This section includes information about the CoolProp software, listings of input HighLevelAPI.rst LowLevelAPI.rst Tabular.rst + Configuration.rst changelog.rst diff --git a/Web/scripts/__init__.py b/Web/scripts/__init__.py index 8c095c32..4a183fd3 100644 --- a/Web/scripts/__init__.py +++ b/Web/scripts/__init__.py @@ -97,7 +97,7 @@ def run_script(path): print "Could not find the file {0}".format(path) # The normal tasks that are carried out each time the script runs -normal_tasks = ["../../dev/scripts/examples/OSXRun.py","coolprop.tabular.speed.py", "fluid_properties.PurePseudoPure.py", "fluid_properties.Mixtures.py","coolprop.parametric_table.py"] +normal_tasks = ["../../dev/scripts/examples/OSXRun.py","coolprop.tabular.speed.py", "fluid_properties.PurePseudoPure.py", "fluid_properties.Mixtures.py","coolprop.parametric_table.py","coolprop.configuration.py"] # The expensive tasks that are fired when full_rebuild is True expensive_tasks = ["fluid_properties.Consistency.py", "fluid_properties.Incompressibles.sh", "logo_2014.py", "fluid_properties.REFPROPcomparison.py"] print "Executing the normal scripts for generating static files." diff --git a/include/Configuration.h b/include/Configuration.h index ec0ab9d5..92b994a9 100644 --- a/include/Configuration.h +++ b/include/Configuration.h @@ -19,18 +19,18 @@ * The type of the default value specifies the only type that will be accepted for this parameter */ #define CONFIGURATION_KEYS_ENUM \ - X(NORMALIZE_GAS_CONSTANTS, "NORMALIZE_GAS_CONSTANTS", true) \ - X(CRITICAL_WITHIN_1UK, "CRITICAL_WITHIN_1UK", true) \ - X(CRITICAL_SPLINES_ENABLED, "CRITICAL_SPLINES_ENABLED", true) \ - X(ALTERNATIVE_REFPROP_PATH, "ALTERNATIVE_REFPROP_PATH", "") \ - X(ALTERNATIVE_REFPROP_HMX_BNC_PATH, "ALTERNATIVE_REFPROP_HMX_BNC_PATH", "") \ - X(SAVE_RAW_TABLES, "SAVE_RAW_TABLES", false) \ - X(MAXIMUM_TABLE_DIRECTORY_SIZE_IN_GB, "MAXIMUM_TABLE_DIRECTORY_SIZE_IN_GB", 1.0) \ - X(DONT_CHECK_PROPERTY_LIMITS, "DONT_CHECK_PROPERTY_LIMITS", false) \ + X(NORMALIZE_GAS_CONSTANTS, "NORMALIZE_GAS_CONSTANTS", true, "If true, for mixtures, the molar gas constant (R) will be set to the CODATA value") \ + X(CRITICAL_WITHIN_1UK, "CRITICAL_WITHIN_1UK", true, "If true, any temperature within 1 uK of the critical temperature will be considered to be AT the critical point") \ + X(CRITICAL_SPLINES_ENABLED, "CRITICAL_SPLINES_ENABLED", true, "If true, the critical splines will be used in the near-vicinity of the critical point") \ + X(SAVE_RAW_TABLES, "SAVE_RAW_TABLES", false, "If true, the raw, uncompressed tables will also be written to file") \ + X(ALTERNATIVE_REFPROP_PATH, "ALTERNATIVE_REFPROP_PATH", "", "An alternative path to be provided to the directory that contains REFPROP's fluids and mixtures directories. If provided, the SETPATH function will be called with this directory prior to calling any REFPROP functions.") \ + X(ALTERNATIVE_REFPROP_HMX_BNC_PATH, "ALTERNATIVE_REFPROP_HMX_BNC_PATH", "", "An alternative path to the HMX.BNC file. If provided, it will be passed into REFPROP's SETUP or SETMIX routines") \ + X(MAXIMUM_TABLE_DIRECTORY_SIZE_IN_GB, "MAXIMUM_TABLE_DIRECTORY_SIZE_IN_GB", 1.0, "The maximum allowed size of the directory that is used to store tabular data") \ + X(DONT_CHECK_PROPERTY_LIMITS, "DONT_CHECK_PROPERTY_LIMITS", false, "If true, when possible, CoolProp will skip checking whether values are inside the property limits") \ // Use preprocessor to create the Enum enum configuration_keys{ - #define X(Enum, String, Default) Enum, + #define X(Enum, String, Default, Desc) Enum, CONFIGURATION_KEYS_ENUM #undef X }; @@ -50,6 +50,12 @@ namespace CoolProp /// Convert the configuration key to a string in a 1-1 representation. std::string config_key_to_string(configuration_keys keys); + +/// Return a string description of the configuration key +std::string config_key_description(configuration_keys keys); + +/// Return a string description of the configuration key (with the key passed as a string) +std::string config_key_description(std::string key); /// A class that contains one entry in configuration /// Can be cast to yield the output value @@ -208,7 +214,7 @@ class Configuration * See http://stackoverflow.com/a/148610 * See http://stackoverflow.com/questions/147267/easy-way-to-use-variables-of-enum-types-as-string-in-c#202511 */ - #define X(Enum, String, Default) \ + #define X(Enum, String, Default, Desc) \ add_item(ConfigurationItem(Enum, Default)); CONFIGURATION_KEYS_ENUM #undef X diff --git a/src/Configuration.cpp b/src/Configuration.cpp index 47c00c92..b0b9b42f 100644 --- a/src/Configuration.cpp +++ b/src/Configuration.cpp @@ -11,7 +11,7 @@ std::string config_key_to_string(configuration_keys keys) * See http://stackoverflow.com/a/148610 * See http://stackoverflow.com/questions/147267/easy-way-to-use-variables-of-enum-types-as-string-in-c#202511 */ - #define X(Enum, String, Default) \ + #define X(Enum, String, Default, Desc) \ case Enum: return String; break; CONFIGURATION_KEYS_ENUM #undef X @@ -19,13 +19,41 @@ std::string config_key_to_string(configuration_keys keys) return ""; // will never get here, just to make compiler happy }; + +std::string config_key_description(configuration_keys keys) +{ + switch (keys) + { + /* ***MAGIC WARNING**!! + * See http://stackoverflow.com/a/148610 + * See http://stackoverflow.com/questions/147267/easy-way-to-use-variables-of-enum-types-as-string-in-c#202511 + */ + #define X(Enum, String, Default, Desc) case Enum: return Desc; break; + CONFIGURATION_KEYS_ENUM + #undef X + } + return ""; // will never get here, just to make compiler happy +}; + +std::string config_key_description(std::string key) +{ + /* ***MAGIC WARNING**!! + * See http://stackoverflow.com/a/148610 + * See http://stackoverflow.com/questions/147267/easy-way-to-use-variables-of-enum-types-as-string-in-c#202511 + */ + #define X(Enum, String, Default, Desc) if (key == String){ return Desc; } + CONFIGURATION_KEYS_ENUM + #undef X + return "INVALID KEY"; +}; + /// Go from string to enum key configuration_keys config_string_to_key(const std::string &s) { /* See http://stackoverflow.com/a/148610 * See http://stackoverflow.com/questions/147267/easy-way-to-use-variables-of-enum-types-as-string-in-c#202511 */ - #define X(Enum, String, Default) \ + #define X(Enum, String, Default, Desc) \ if (s == String){ return Enum; } CONFIGURATION_KEYS_ENUM #undef X diff --git a/wrappers/Python/CoolProp/CoolProp.pxd b/wrappers/Python/CoolProp/CoolProp.pxd index 935d2a58..fc51a9e3 100644 --- a/wrappers/Python/CoolProp/CoolProp.pxd +++ b/wrappers/Python/CoolProp/CoolProp.pxd @@ -18,6 +18,7 @@ cdef extern from "CoolPropTools.h" namespace "CoolProp": cdef extern from "Configuration.h" namespace "CoolProp": string _get_config_as_json_string "CoolProp::get_config_as_json_string"() except + void _set_config_as_json_string "CoolProp::set_config_as_json_string"(string) except + + string _config_key_description "CoolProp::config_key_description"(string) except + cdef extern from "DataStructures.h" namespace "CoolProp": string _get_mixture_binary_pair_data "CoolProp::get_mixture_binary_pair_data"(const string CAS1, const string CAS2, const string key) except + diff --git a/wrappers/Python/CoolProp/CoolProp.pyx b/wrappers/Python/CoolProp/CoolProp.pyx index 52647216..d7cc17dd 100644 --- a/wrappers/Python/CoolProp/CoolProp.pyx +++ b/wrappers/Python/CoolProp/CoolProp.pyx @@ -133,6 +133,12 @@ cpdef string get_config_as_json_string(): Values can be set by passing a modified json library (converted to string) to set_config_as_json_string """ return _get_config_as_json_string() + +cpdef string config_key_description(string key): + """ + Obtain the string description for a configuration key. Python wrapper of C++ function :cpapi:`CoolProp::config_key_description` + """ + return _config_key_description(key) cpdef set_config_as_json_string(string s): """