Skip to content

App

all_units(reference=None)

Get all available units in the reference

Parameters

reference : str, optional The reference name such as 'PRESSURE', 'TEMPERATURE', ...

Returns

List[str] A list of all available units

Raises

Exception If getting all units fails

Source code in pycuc/app.py 
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
def all_units(
        reference: Optional[str] = None
) -> List[str]:
    '''
    Get all available units in the reference

    Parameters
    ----------
    reference : str, optional
        The reference name such as 'PRESSURE', 'TEMPERATURE', ...

    Returns
    -------
    List[str]
        A list of all available units

    Raises
    ------
    Exception
        If getting all units fails
    '''
    try:
        # NOTE: validate reference
        if reference:
            if not isinstance(reference, str) or len(reference) == 0:
                raise Exception('Reference not provided!')

            # SECTION: get units based on reference
            if reference.upper() in Refs._reference:
                return Refs.get_reference_units_by_key(reference.upper())

        # SECTION: get all units
        return Refs.get_all_reference_units()
    except Exception as e:
        logger.error('Getting all units failed!, ', e)
        return []

check_reference(reference, dataframe=True)

Shows reference unit table

Parameters

reference : str reference name such as pressure, temperature, custom dataframe : bool, optional If True, then return a dataframe, otherwise return a dict

Returns

reference : dict | dataframe reference details

Notes

  1. The reference can be set to 'PRESSURE', 'TEMPERATURE', 'CUSTOM'

Examples

! pressure

print(pycuc.check_reference('pressure'))

! temperature

print(pycuc.check_reference('temperature'))

! custom

print(pycuc.check_reference('custom'))

Source code in pycuc/app.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
def check_reference(reference: str, dataframe: bool = True):
    '''
    Shows reference unit table

    Parameters
    ----------
    reference : str
        reference name such as pressure, temperature, custom
    dataframe : bool, optional
        If True, then return a dataframe, otherwise return a dict

    Returns
    -------
    reference : dict | dataframe
        reference details

    Notes
    ------
    1. The reference can be set to 'PRESSURE', 'TEMPERATURE', 'CUSTOM'

    Examples
    --------
    >>> # ! pressure
    >>> print(pycuc.check_reference('pressure'))

    >>> # ! temperature
    >>> print(pycuc.check_reference('temperature'))

    >>> # ! custom
    >>> print(pycuc.check_reference('custom'))
    '''
    try:
        # check reference
        if isinstance(reference, str) and len(reference) > 0:
            cucC = CustomUnitConverter('', '')
            # check reference
            return cucC.check_reference(reference, dataframe)
        else:
            raise Exception('Reference not provided!')

    except Exception as e:
        raise Exception('Checking references failed!, ', e)

check_version()

Check the version of the package

Returns

str The version of the package

Source code in pycuc/app.py 
23
24
25
26
27
28
29
30
31
32
def check_version():
    '''
    Check the version of the package

    Returns
    -------
    str
        The version of the package
    '''
    return __version__

convert_from_to(value, from_unit, to_unit, reference=None)

Convert a value from one unit to another

Parameters

value : float The value to be converted from_unit : str The unit of the value to_unit : str The unit to convert to reference : str, optional The reference name such as 'PRESSURE', 'TEMPERATURE', 'CUSTOM'

Returns

float The converted value

Notes

  1. The reference can be set to 'PRESSURE', 'TEMPERATURE', 'CUSTOM'
  2. If reference is None, then automatically set a value

Examples

! pressure

print(pycuc.convert_from_to(1, 'MPa', 'Pa'))

! temperature

print(pycuc.convert_from_to(358, 'K', 'C')) print(pycuc.convert_from_to(25, 'C', 'K'))

Source code in pycuc/app.py 
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
def convert_from_to(
    value: float,
    from_unit: str,
    to_unit: str,
    reference: Optional[str] = None,
) -> float:
    '''
    Convert a value from one unit to another

    Parameters
    ----------
    value : float
        The value to be converted
    from_unit : str
        The unit of the value
    to_unit : str
        The unit to convert to
    reference : str, optional
        The reference name such as 'PRESSURE', 'TEMPERATURE', 'CUSTOM'

    Returns
    -------
    float
        The converted value

    Notes
    ------
    1. The reference can be set to 'PRESSURE', 'TEMPERATURE', 'CUSTOM'
    2. If reference is None, then automatically set a value

    Examples
    --------
    >>> # ! pressure
    >>> print(pycuc.convert_from_to(1, 'MPa', 'Pa'))
    >>>
    >>> # ! temperature
    >>> print(pycuc.convert_from_to(358, 'K', 'C'))
    >>> print(pycuc.convert_from_to(25, 'C', 'K'))
    '''
    try:
        # custom object
        CustomUnitConverterC = CustomUnitConverter(value, from_unit)

        # conversion
        return CustomUnitConverterC.convert(to_unit, reference)

    except Exception as e:
        raise Exception('Conversion failed, ', e)

create_cuc(value, unit)

Define a CustomUnitConverter object

Parameters

value : float The value to be converted unit : str The unit of the value

Returns

CustomUnitConverter A CustomUnitConverter object

Examples

! pressure

my_cuc_1 = pycuc.create_cuc(1, 'MPa')

convert to Pa

print(my_cuc_1.convert('Pa'))

print(my_cuc_1.convert('bar'))

print(my_cuc_1.convert('kPa'))

! temperature

my_cuc_2 = pycuc.create_cuc(358, 'K')

convert to K

print(my_cuc_2.convert('C'))

print(my_cuc_2.convert('F'))

print(my_cuc_2.convert('R'))

! heat capacity unit: J/mol.K

my_cuc_3 = pycuc.create_cuc(25, 'J/mol.K')

add custom

my_cuc_3.add_custom_unit('J/mol.K', 1) my_cuc_3.add_custom_unit('kJ/mol.K', 1000)

conversion

print(my_cuc_3.convert('J/mol.K')) print(my_cuc_3.convert('kJ/mol.K'))

Source code in pycuc/app.py 
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
def create_cuc(
        value: float,
        unit: str
) -> CustomUnitConverter:
    '''
    Define a CustomUnitConverter object

    Parameters
    ----------
    value : float
        The value to be converted
    unit : str
        The unit of the value

    Returns
    -------
    CustomUnitConverter
        A CustomUnitConverter object

    Examples
    --------
    >>> # ! pressure
    >>> my_cuc_1 = pycuc.create_cuc(1, 'MPa')
    >>> # convert to Pa
    >>> print(my_cuc_1.convert('Pa'))

    >>> print(my_cuc_1.convert('bar'))

    >>> print(my_cuc_1.convert('kPa'))
    >>>
    >>> # ! temperature
    >>> my_cuc_2 = pycuc.create_cuc(358, 'K')
    >>> # convert to K
    >>> print(my_cuc_2.convert('C'))

    >>> print(my_cuc_2.convert('F'))

    >>> print(my_cuc_2.convert('R'))
    >>>
    >>> # ! heat capacity unit: J/mol.K
    >>> my_cuc_3 = pycuc.create_cuc(25, 'J/mol.K')
    >>> # add custom
    >>> my_cuc_3.add_custom_unit('J/mol.K', 1)
    >>> my_cuc_3.add_custom_unit('kJ/mol.K', 1000)

    >>> # conversion
    >>> print(my_cuc_3.convert('J/mol.K'))
    >>> print(my_cuc_3.convert('kJ/mol.K'))

    '''
    return CustomUnitConverter(value, unit)

go(reference_file=None)

Initializes app with/without external yml file

Parameters

reference_file : str, optional The path to the yml reference file

Returns

cucx : CustomUnitConverterX A CustomUnitConverterX object

Notes

  1. The reference can be set to 'PRESSURE', 'TEMPERATURE', 'CUSTOM'
  2. If reference_file is not None, then the app will load the yml file
yml reference file format is as:
CUSTOM-UNIT

HEAT-CAPACITY: J/mol.K : 1 kJ/mol.K : 0.001 J/kmol.K : 1000 ENERGY: J/mol : 1 kJ/mol : 0.001 J/kmol : 1000 kcal/mol: 0.000239006 cal/mol: 0.239006

Source code in pycuc/app.py 
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
def go(reference_file: Optional[str] = None) -> CustomUnitConverterX:
    '''
    Initializes app with/without external yml file

    Parameters
    ----------
    reference_file : str, optional
        The path to the yml reference file

    Returns
    -------
    cucx : CustomUnitConverterX
        A CustomUnitConverterX object

    Notes
    ------
    1. The reference can be set to 'PRESSURE', 'TEMPERATURE', 'CUSTOM'
    2. If reference_file is not None, then the app will load the yml file

    ### yml reference file format is as:

    CUSTOM-UNIT:
        HEAT-CAPACITY:
            J/mol.K : 1
            kJ/mol.K : 0.001
            J/kmol.K : 1000
        ENERGY:
            J/mol : 1
            kJ/mol : 0.001
            J/kmol : 1000
            kcal/mol: 0.000239006
            cal/mol: 0.239006
    '''
    try:
        # init
        cucxC = CustomUnitConverterX('', '')
        # load external custom unit
        # check
        if reference_file is not None:
            # check file exists
            if not os.path.exists(reference_file):
                raise Exception('File not found!')
            # load
            cucxC.load_custom_unit(reference_file)

        # return
        return cucxC
    except Exception as e:
        raise Exception("Initializing failed!, ", e)

is_unit_available(unit, reference=None)

Check if a unit is available in the reference

Parameters

unit : str The unit to check reference : str, optional The reference name such as 'PRESSURE', 'TEMPERATURE', ...

Returns

bool True if the unit is available, False otherwise

Raises

Exception If checking unit availability fails

Source code in pycuc/app.py 
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
def is_unit_available(
        unit: str,
        reference: Optional[str] = None
) -> bool:
    '''
    Check if a unit is available in the reference

    Parameters
    ----------
    unit : str
        The unit to check
    reference : str, optional
        The reference name such as 'PRESSURE', 'TEMPERATURE', ...

    Returns
    -------
    bool
        True if the unit is available, False otherwise

    Raises
    ------
    Exception
        If checking unit availability fails
    '''
    try:
        # NOTE: validate reference
        if reference:
            if not isinstance(reference, str) or len(reference) == 0:
                raise Exception('Reference not provided!')

            # SECTION: check unit based on reference
            if reference.upper() in Refs._reference:
                return Refs.is_unit_in_reference_by_key(unit, reference.upper())

        # SECTION: check in all units
        return Refs.is_unit_in_reference(unit)
    except Exception as e:
        logger.error('Checking unit availability failed!, ', e)
        return False

to(value, unit_conversion_block, reference=None)

Convert a value from one unit to another using unit conversion block

Parameters

value : float The value to be converted unit_conversion_block : str The block shows (from_unit => to_unit) such as (MPa => Pa), (K => C) reference : str, optional The reference name such as 'PRESSURE', 'TEMPERATURE', 'CUSTOM'

Returns

float The converted value

Notes

  1. The reference can be set to 'PRESSURE', 'TEMPERATURE', 'CUSTOM'
  2. If reference is None, then automatically set a value

Examples

! pressure

print(pycuc.to(1, 'MPa => Pa'))

! temperature

print(pycuc.to(358, 'K => C')) print(pycuc.to(25, 'C => K'))

Source code in pycuc/app.py 
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
def to(
    value: float,
    unit_conversion_block: str,
    reference: Optional[str] = None,
) -> float:
    '''
    Convert a value from one unit to another using `unit conversion block`

    Parameters
    ----------
    value : float
        The value to be converted
    unit_conversion_block : str
        The block shows `(from_unit => to_unit)` such as (MPa => Pa), (K => C)
    reference : str, optional
        The reference name such as 'PRESSURE', 'TEMPERATURE', 'CUSTOM'

    Returns
    -------
    float
        The converted value

    Notes
    ------
    1. The reference can be set to 'PRESSURE', 'TEMPERATURE', 'CUSTOM'
    2. If reference is None, then automatically set a value

    Examples
    --------
    >>> # ! pressure
    >>> print(pycuc.to(1, 'MPa => Pa'))
    >>>
    >>> # ! temperature
    >>> print(pycuc.to(358, 'K => C'))
    >>> print(pycuc.to(25, 'C => K'))
    '''
    try:
        # check conversion block
        from_unit, block_symbol, to_unit = Utils(
        ).parse_conversion_block(unit_conversion_block)

        return convert_from_to(value, from_unit, to_unit, reference)

    except Exception as e:
        raise Exception('Conversion failed, ', e)