Extending and proofreading the documentation.

CONTRIBUTORS.md

@@ -3,10 +3,11 @@
 ## Project Leads
 
 * [Harshal Pohekar](https://github.com/hpohekar)
-* [Alexander Carvalho](https://github.com/acarvalh-work)
 
 ## Individual Contributors
 
 * [Sean Pearson](https://github.com/seanpearsonuk)
 * [Mainak Kundu](https://github.com/mkundu1)
 * [Prithwish Mukherjee](https://github.com/prmukherj)
+* [Alexander Carvalho](https://github.com/acarvalh-work)
+* [Adam Boutin]([https:](https://github.com/ansaboutin))

README.rst

@@ -92,8 +92,8 @@ Getting started
 
 Basic usage
 ~~~~~~~~~~~
-
-Import the ``ansys.units`` package:
+PyAnsys Units supports defining quantities and their units in a intuitive way.
+Start by importing the ``ansys.units`` package:
 
 .. code:: python
 
@@ -103,14 +103,14 @@ You can instantiate quantities with one of four methods:
 
 .. code:: python
 
-   # unit string
+   # Using unit strings
 
    volume = ansunits.Quantity(value=1, units="m^3")
 
    volume.value  # 1.0
    volume.units.name  # "m^3"
 
-   # unit instance
+   # Using Unit instances
 
    ureg = ansunits.UnitRegistry()
 
@@ -119,7 +119,7 @@ You can instantiate quantities with one of four methods:
    volume.value  # 1.0
    volume.units.name  # "kg"
 
-   # dimensions
+   # Using base dimensions
 
    dims = ansunits.BaseDimensions
    dimensions = ansunits.Dimensions({dims.LENGTH: 1, dims.TIME: -2})
@@ -129,7 +129,7 @@ You can instantiate quantities with one of four methods:
    acceleration.value  # 3.0
    acceleration.units.name  # "m s^-2"
 
-   # quantity map
+   # Using the quantity map
 
    torque = ansunits.Quantity(5, quantity_map={"Torque": 1})
 
@@ -141,8 +141,14 @@ You can instantiate unit systems with one of two methods:
 
 .. code:: python
 
-   # custom unit systems, any unit type that is not given will be filled with SI
-   # equivalent.
+   # Use a pre-defined unit system
+
+   si = ansunits.UnitSystem(unit_sys="SI")
+
+   si.base_units  # ['kg', 'm', 's', 'K', 'delta_K', 'radian', 'mol', 'cd', 'A', 'sr']
+
+   # Custom unit systems are defined by passing selected base units. Any unit
+   # type that is not given will be filled with the SI equivalent.
 
    ureg = ansunits.UnitRegistry()
    dims = ansunits.BaseDimensions
@@ -159,12 +165,6 @@ You can instantiate unit systems with one of two methods:
 
    sys.base_units  # ['slug', 'ft', 's', 'R', 'delta_R', 'radian', 'slugmol', 'cd', 'A', 'sr']
 
-   # pre-defined unit systems
-
-   si = ansunits.UnitSystem(unit_sys="SI")
-
-   si.base_units  # ['kg', 'm', 's', 'K', 'delta_K', 'radian', 'mol', 'cd', 'A', 'sr']
-
 Examples
 ~~~~~~~~
 

doc/.vale.ini

@@ -20,7 +20,7 @@ WordTemplate = \b(?:%s)\b
 Packages = Google
 
 # Define the Ansys vocabulary
-Vocab = ANSYS, PyAnsys
+Vocab = ANSYS
 
 [*.{md,rst}]
 

doc/source/getting_started/faq.rst

@@ -0,0 +1,41 @@
+.. _frequently:
+
+==========================
+Frequently asked questions
+==========================
+
+What is PyAnsys Units?
+""""""""""""""""""""""
+PyAnsys units is a Python package that allows you to introduce the concept of
+physical quantities into your Python environment. You can define your own units,
+unit systems and quantities and work with them in a natural way using arithmetic
+operations and conversions.
+
+What unit systems are provided by default?
+""""""""""""""""""""""""""""""""""""""""""
+PyAnsys Units provides the following unit systems by default:
+
+- `International System of Units <https://en.wikipedia.org/wiki/International_System_of_Units>`_ (SI)
+- `Centimetre gram second <https://en.wikipedia.org/wiki/Centimetre–gram–second_system_of_units>`_ (CGS)
+- British Technical (BT)
+
+British technical units define the mass units as the ``slug``, length units as
+``ft`` and time units of ``s``, which leads to pound-force, ``lbf``, being the
+force units. You can introduce your own unit systems either dynamically at run
+time or by providing a custom configuration file.
+
+PyAnsys Units defines a unit system as a `unique selection` of base units. For
+instance, the SI unit system is a unique choice of units for the default base
+units.
+
+How is PyAnsys Units different from pint?
+"""""""""""""""""""""""""""""""""""""""""
+
+In contrast to pint, the ``UnitRegistry`` is only a container of the configured
+``Unit`` objects. The registry does not contain additional information. Notably
+the ``UnitSystem`` is a standalone class. When creating a ``Unit`` using
+``Dimensions`` it requires a unit system parameter to be passed in for non-SI
+units.
+
+PyAnsys Units treats all angles as dimensional units. With this behavior the
+conversion from rad/s to Hz is not allowed.

doc/source/getting_started/index.rst

@@ -5,11 +5,148 @@ Getting started
 ===============
 
 PyAnsys Units provides a Pythonic interface for units, unit systems, and unit
-conversions.
+conversions. Once imported the package is initialized with units and unit
+systems for you to use, and is fully customizable if something you need is not
+present.
+
+Basic usage
+-----------
+PyAnsys Units supports defining quantities and their units in a intuitive way.
+Start by importing the ``ansys.units`` package:
+
+.. code:: python
+
+   import ansys.units as ansunits
+
+You can instantiate quantities with one of four methods:
+
+.. code:: python
+
+   # Using supported unit strings
+
+   volume = ansunits.Quantity(value=1, units="m^3")
+
+   volume.value  # 1.0
+   volume.units.name  # "m^3"
+
+   # Using Unit instances
+
+   ureg = ansunits.UnitRegistry()
+
+   mass = ansunits.Quantity(value=1, units=ureg.kg)
+
+   volume.value  # 1.0
+   volume.units.name  # "kg"
+
+   # Using base dimensions
+
+   dims = ansunits.BaseDimensions
+   dimensions = ansunits.Dimensions({dims.LENGTH: 1, dims.TIME: -2})
+
+   acceleration = ansunits.Quantity(value=3, dimensions=dimensions)
+
+   acceleration.value  # 3.0
+   acceleration.units.name  # "m s^-2"
+
+   # Using the quantity map
+
+   torque = ansunits.Quantity(5, quantity_map={"Torque": 1})
+
+   torque.value  # 5.0
+   torque.units.name  # "N m"
+   torque.si_units  # "kg m^2 s^-2"
+
+You can instantiate unit systems with one of two methods:
+
+.. code:: python
+
+   # Use a pre-defined unit system
+
+   si = ansunits.UnitSystem(unit_sys="SI")
+
+   si.base_units  # ['kg', 'm', 's', 'K', 'delta_K', 'radian', 'mol', 'cd', 'A', 'sr']
+
+   # Custom unit systems are defined by passing selected base units. Any unit
+   # type that is not given defaults to SI.
+
+   ureg = ansunits.UnitRegistry()
+   dims = ansunits.BaseDimensions
+
+   sys = ansunits.UnitSystem(
+       base_units={
+           dims.MASS: ureg.slug,
+           dims.LENGTH: ureg.ft,
+           dims.TEMPERATURE: ureg.R,
+           dims.TEMPERATURE_DIFFERENCE: ureg.delta_R,
+           dims.CHEMICAL_AMOUNT: ureg.slugmol,
+       }
+   )
+
+   sys.base_units  # ['slug', 'ft', 's', 'R', 'delta_R', 'radian', 'slugmol', 'cd', 'A', 'sr']
+
+Examples
+--------
+
+Perform arithmetic operations:
+
+.. code:: python
+
+   import ansys.units as ansunits
+
+   deg = ansunits.Quantity(90, "degree")
+   math.sin(deg)  # 1.0
+
+   v1 = ansunits.Quantity(10.0, "m s^-1")
+   v2 = ansunits.Quantity(5.0, "m s^-1")
+
+   v3 = v1 - v2
+   v3.value  # 5.0
+
+   vpow = v1**2
+   vpow.value  # 100.0
+   vpow.units  # "m^2 s^-2"
+
+Directly convert values to another set of units:
+
+.. code:: python
+
+   import ansys.units as ansunits
+
+   flbs = ansunits.Quantity(1, "lb ft^-1 s^-1")
+   flbs.value  # 1
+
+   pas = flbs.to("Pa s")
+   pas.value  # 1.4881639435695542
+   pas.units.name  # 'Pa s'
+
+Use a custom unit system to perform conversions:
+
+.. code:: python
+
+   import ansys.units as ansunits
+
+   ureg = ansunits.UnitRegistry()
+   dims = ansunits.BaseDimensions
+
+   sys = ansunits.UnitSystem(
+       base_units={
+           dims.MASS: ureg.slug,
+           dims.LENGTH: ureg.ft,
+           dims.TEMPERATURE: ureg.R,
+           dims.TEMPERATURE_DIFFERENCE: ureg.delta_R,
+           dims.CHEMICAL_AMOUNT: ureg.slugmol,
+       }
+   )
+
+   v = ansunits.Quantity(10, "kg m s^2")
+   v2 = sys.convert(v)
+
+   v2.value  # 2.2480894309971045
+   v2.units.name  # 'slug ft s^2'
 
 .. toctree::
    :hidden:
    :maxdepth: 2
 
    installation
-   frequently
+   faq

doc/source/user_guide/index.rst

@@ -12,5 +12,6 @@ code to work with physical quantities.
    :maxdepth: 2
 
    quantity
+   strings
    temperature
 

doc/source/user_guide/quantity.rst

@@ -1,7 +1,7 @@
 .. _quantity:
 
 ===================
-Defining a Quantity
+Defining a quantity
 ===================
 
 The default unit system used when performing quantity operations is SI. This

doc/source/user_guide/strings.rst

@@ -0,0 +1,35 @@
+.. _strings:
+
+==================
+Unit string format
+==================
+
+PyAnsys Units supports specifying units as strings for many input parameters and
+can also provide string representations of units. The basic form of a unit
+string follows this convention:
+
+.. code::
+
+    <multiplier prefix>[unit]<^exponent>
+
+where
+
+- ``multiplier prefix`` is optional and must be one of the prefixes defined on
+  package initialization such as ``k``, ``M`` or ``c``.
+- ``unit`` must be one of the base or derived units as defined in the
+  ``UnitRegistry``.
+- ``exponent`` is optional and must be preceded by the caret ``^`` symbol followed
+  by the numerical exponent.
+
+More complex unit strings can be built up by concatenation of these basic strings
+with spaces in between. Spaces between the sub-strings indicate that the units
+are multiplied together. Some examples are as follows:
+
+.. code:: python
+
+    accel_mps = "m s^-2.0"
+    density = "kg m^-3.0"
+    proportional_const = "ft s^-2.5 psi^-1.0"
+
+You can inspect the unit tests and documentation examples to see more usage of
+unit strings.

doc/source/user_guide/temperature.rst

@@ -1,12 +1,12 @@
 .. _temperature:
 
-===================================
-Temperature & Change of Temperature
-===================================
+======================================
+Temperature and temperature difference
+======================================
 
-PyAnsys Units supports temperature units in Kelvin (K), Celsius (C), Rankine (R)
-and Fahrenheit (F). For each temperature unit there is a change of temperature
-unit which is prefixed with ``delta_``.
+PyAnsys Units supports temperature units in kelvin (K), celsius (C), rankine (R)
+and fahrenheit (F). For each temperature unit there is a corresponding
+temperature difference unit which is prefixed with ``delta_``.
 
 Conversion is handled naturally through arithmetic operations:
 
@@ -27,8 +27,8 @@ Conversion is handled naturally through arithmetic operations:
     delta_K_ad_delta_K = delta_K + delta_K  # (10, delta_K)
     delta_K_sb_delta_K = delta_K - delta_K  # (0, delta_K)
 
-Negative absolute values for any temperature are instantiated as a change in
-temperature.
+Negative absolute values for any temperature are instantiated as a temperature
+difference.
 
 .. code:: python