.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "examples/00-pyunits/basic_usage.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code .. rst-class:: sphx-glr-example-title .. _sphx_glr_examples_00-pyunits_basic_usage.py: .. _ref_basic_usage: PyAnsys Units basics -------------------- PyAnsys Units provides a Pythonic interface for units, unit systems, and unit conversions. Its features enable seamless setup and usage of physical quantities. This example shows you how to perform these tasks: - Create quantities (unit strings, dimensions, and quantity tables). - Access different quantity properties. - Perform arithmetic operations. - Perform unit conversions. - Create unit systems (custom and predefined). - Apply unit systems to quantities. .. GENERATED FROM PYTHON SOURCE LINES 18-21 .. code-block:: Python # sphinx_gallery_thumbnail_path = '_static/basic_usage.png' .. GENERATED FROM PYTHON SOURCE LINES 22-25 Perform required imports ~~~~~~~~~~~~~~~~~~~~~~~~ Import the ``ansys.units`` package. .. GENERATED FROM PYTHON SOURCE LINES 25-29 .. code-block:: Python from ansys.units import BaseDimensions, Dimensions, Quantity, UnitSystem from ansys.units.quantity import get_si_value .. GENERATED FROM PYTHON SOURCE LINES 30-36 Create quantities ~~~~~~~~~~~~~~~~~ You can instantiate quantities using one of three methods: - Unit strings : str, Unit - Dimensions : Dimensions - Quantity table : dict .. GENERATED FROM PYTHON SOURCE LINES 36-69 .. code-block:: Python # Unit strings volume = Quantity(value=1, units="m^3") acceleration = Quantity(value=3, units="m s^-2") torque = Quantity(value=5, units="N m") # Dimensions dims = BaseDimensions vol_dims = Dimensions({dims.LENGTH: 3}) volume = Quantity(value=1, dimensions=vol_dims) acc_dims = Dimensions({dims.LENGTH: 1, dims.TIME: -2}) acceleration = Quantity(value=3, dimensions=acc_dims) tor_dims = Dimensions({dims.MASS: 1, dims.LENGTH: 2, dims.TIME: -2}) torque = Quantity(value=5, dimensions=tor_dims) # Quantity table vol_dict = {"Volume": 1} volume = Quantity(value=1, quantity_table=vol_dict) acc_dict = {"Acceleration": 1} acceleration = Quantity(value=3, quantity_table=acc_dict) tor_dict = {"Torque": 1} torque = Quantity(value=5, quantity_table=tor_dict) .. GENERATED FROM PYTHON SOURCE LINES 70-73 Specify quantity properties ~~~~~~~~~~~~~~~~~~~~~~~~~~~ For a quantity, you specify six properties: .. GENERATED FROM PYTHON SOURCE LINES 73-92 .. code-block:: Python # 1. value : float | int # 2. units : str # 3. si_value : float | int # 4. si_units : str # 5. dimensions : dict # 6. is_dimensionless : bool dv_dict = {"DynamicViscosity": 1} dynamic_viscosity = Quantity(value=50, quantity_table=dv_dict) dynamic_viscosity.value # >>> 50.0 dynamic_viscosity.units.name # >>> "Pa s" dynamic_viscosity.units.si_units # >>> "kg m^-1 s^-1" dynamic_viscosity.dimensions # >>> {'MASS': 1.0, 'LENGTH': -1.0, 'TIME': -1.0} dynamic_viscosity.is_dimensionless # >>> False get_si_value(dynamic_viscosity) # >>> 50.0 .. rst-class:: sphx-glr-script-out .. code-block:: none 50.0 .. GENERATED FROM PYTHON SOURCE LINES 93-96 Perform arithmetic operations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can perform all mathematical operations on a quantity. .. GENERATED FROM PYTHON SOURCE LINES 96-149 .. code-block:: Python import math q1 = Quantity(10.0, "m s^-1") q2 = Quantity(5.0, "m s^-1") # Subtraction q3 = q2 - q1 q3.value # >>> 5.0 q3.units.name # >>> "m s^-1" # Addition q4 = q2 + q1 q4.value # >>> 15.0 q4.units.name # >>> "m s^-1" # Division q5 = q2 / q1 q5.value # >>> 2.0 q5.units.name # >>> None # Multiplication q6 = q2 * q1 q6.value # >>> 50.0 q6.units.name # >>> "m^2 s^-2" # Negation q7 = -q2 q7.value # >>> -5.0 q7.units.name # >>> "m s^-1" # Exponents q8 = q1**2 q8.value # >>> 100.0 q8.units.name # >>> "m^2 s^-2" # Roots q9 = Quantity(5.0, "") math.sqrt(q9) # >>> 2.2360679775 # Trigonometry math.sin(Quantity(90, "degree")) # >>> 1.0 math.cos(Quantity(math.pi, "radian")) # >>> -1.0 .. rst-class:: sphx-glr-script-out .. code-block:: none -1.0 .. GENERATED FROM PYTHON SOURCE LINES 150-153 Perform conversions ~~~~~~~~~~~~~~~~~~~ To check the compatible units use the 'compatible_units' method. .. GENERATED FROM PYTHON SOURCE LINES 153-176 .. code-block:: Python slug = Quantity(value=5, units="slug") slug.compatible_units() # >>> {'lbm', 'g', 'lb', 'kg'} # You can perform conversions on quantities with compatible units. kg = slug.to("kg") kg.value # >>> 72.96951468603184 kg.units.name # >>> "kg" m = Quantity(value=25, units="m") cm = m.to("cm") cm.value # >>> 2500 cm.units.name # >>> "cm" dvis = Quantity(1.0, "lb ft^-1 s^-1") pas = dvis.to("Pa s") pas.value # >>> 1.4881639435695542 pas.units.name # >>> "Pa s" .. rst-class:: sphx-glr-script-out .. code-block:: none 'Pa s' .. GENERATED FROM PYTHON SOURCE LINES 177-185 Instantiate unit systems ~~~~~~~~~~~~~~~~~~~~~~~~ You can instantiate unit systems using a few methods: - Custom units - Predefined unit systems - Copy from a preexisting unit system - Combinations of these .. GENERATED FROM PYTHON SOURCE LINES 185-260 .. code-block:: Python # Custom units dims = BaseDimensions sys_units = {dims.MASS: "slug", dims.LENGTH: "ft"} sys = UnitSystem(base_units=sys_units, system="SI") sys """ MASS: slug LENGTH: ft TIME: s TEMPERATURE: K TEMPERATURE_DIFFERENCE: delta_K ANGLE: radian CHEMICAL_AMOUNT: mol LIGHT: cd CURRENT: A SOLID_ANGLE: sr """ # Predefined unit systems cgs = UnitSystem(system="CGS") cgs """ MASS: g LENGTH: cm TIME: s TEMPERATURE: K TEMPERATURE_DIFFERENCE: delta_K ANGLE: radian CHEMICAL_AMOUNT: mol LIGHT: cd CURRENT: A SOLID_ANGLE: sr """ # Copy from a preexisting unit system cgs_copy = UnitSystem(copy_from=cgs) cgs_copy """ MASS: g LENGTH: cm TIME: s TEMPERATURE: K TEMPERATURE_DIFFERENCE: delta_K ANGLE: radian CHEMICAL_AMOUNT: mol LIGHT: cd CURRENT: A SOLID_ANGLE: sr """ # Combinations of these sys_units = {dims.MASS: "slug", dims.LENGTH: "ft", dims.ANGLE: "degree"} cgs_modified = UnitSystem(base_units=sys_units, copy_from=cgs) cgs_modified """ MASS: slug LENGTH: ft TIME: s TEMPERATURE: K TEMPERATURE_DIFFERENCE: delta_K ANGLE: degree CHEMICAL_AMOUNT: mol LIGHT: cd CURRENT: A SOLID_ANGLE: sr """ .. rst-class:: sphx-glr-script-out .. code-block:: none '\nMASS: slug\nLENGTH: ft\nTIME: s\nTEMPERATURE: K\nTEMPERATURE_DIFFERENCE: delta_K\nANGLE: degree\nCHEMICAL_AMOUNT: mol\nLIGHT: cd\nCURRENT: A\nSOLID_ANGLE: sr\n' .. GENERATED FROM PYTHON SOURCE LINES 261-264 Create a unit system independently ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can create a unit system independently and apply it to quantities. .. GENERATED FROM PYTHON SOURCE LINES 264-274 .. code-block:: Python si = UnitSystem() feet_per_second = Quantity(value=11.2, units="ft s^-1") meters_per_second = feet_per_second.convert(si) meters_per_second.value # >>> 3.4137599999999995 meters_per_second.units # >>> "m s^-1" .. rst-class:: sphx-glr-script-out .. code-block:: none _dimensions: {'LENGTH': 1.0, 'TIME': -1.0} _name: m s^-1 _si_units: m s^-1 _si_scaling_factor: 1.0 _si_offset: 0.0 .. GENERATED FROM PYTHON SOURCE LINES 275-278 Using preferred units ~~~~~~~~~~~~~~~~~~~~~ Specify a list of units that quantities will automatically convert to. .. GENERATED FROM PYTHON SOURCE LINES 278-289 .. code-block:: Python Quantity.preferred_units(units=["J"]) torque = Quantity(1, quantity_table={"Torque": 1}) torque # >>> Quantity (1.0, "J") ten_N = Quantity(10, units="N") ten_m = Quantity(10, units="m") joules = ten_N * ten_m joules # >>> Quantity (100.0, "J") .. rst-class:: sphx-glr-script-out .. code-block:: none Quantity (100.0, "J") .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 0.010 seconds) .. _sphx_glr_download_examples_00-pyunits_basic_usage.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: basic_usage.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: basic_usage.py ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_