mp-units/docs/getting_started/introduction.md

# Introduction

**mp-units** is a Modern C++ library that provides compile-time dimensional analysis and unit/quantity
manipulation. The initial versions of the library were inspired by the
[`std::chrono::duration`](https://en.cppreference.com/w/cpp/chrono/duration)
but with each release, the interfaces diverged from the original to provide a better user
experience.

!!! info

    A brief introduction to the library's interfaces and the rationale for changes in the version 2.0
    of **mp-units** were provided in detail by [Mateusz Pusz](https://github.com/mpusz) in the
    ["mp-units: Lessons Learned and a New C++ Library Design" talk at the ACCU 2023 conference](https://www.youtube.com/watch?v=l0rXdJfXLZc).


## Open Source

**mp-units** is Free and Open Source, with a permissive
[MIT license](https://github.com/mpusz/mp-units/blob/master/LICENSE.md). Check out the source
code and issue tracking (for questions and support, reporting bugs, suggesting feature requests
and improvements) at <https://github.com/mpusz/mp-units>.


## With the User's Experience in Mind

Most of the critical design decisions in the library are dictated by the requirement of
providing the best user experience possible. Other C++ physical units libraries are
"famous" for their enormous and hard-to-understand error messages (one line of the error log often
do not fit on one slide). The ultimate goal of **mp-units** is to improve this and make compile-time
errors and debugging as easy and user-friendly as possible.

To achieve this goal, several techniques are applied:

- usage of C++20 concepts,
- [using strong types for framework entities (instead of type aliases)](../users_guide/framework_basics/interface_introduction.md#strong-types-instead-of-aliases),
- [usage of expression templates to improve the readability of generated types](../users_guide/framework_basics/interface_introduction.md#expression-templates),
- limiting the number of template arguments to the bare minimum.

!!! important

    In many generic C++ libraries compile-time errors do not happen often. It is hard to
    break `std::string` or `std::vector` in a way it won't compile with a huge error
    log. Physical Units libraries are different. **Generation of compile-time errors
    is the main reason to use such a library.**


## Key Features

| Feature                      | Description                                                                                                                                                                                                                                                                                                                                         |
|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Safety**                   | - [The affine space strong types] (`quantity` and `quantity_point`)<br>- [Compile-time checked conversions of quantities and units]<br>- [Unique support for many quantities of the same kind]<br>- [Type-safe equations on scalar, vector, and tensor quantities and their units]<br>- [Value-preserving conversions]                              |
| **Performance**              | - All the compile-time logic implemented as immediate (`consteval`) functions<br>- As fast or even faster than working with fundamental types<br>- No space size overhead needed to implement high-level abstractions                                                                                                                               |
| **Great User Experience**    | - [Optimized for readable compilation errors and great debugging experience]<br>- [Efficient and composable way to specify a unit of choice]<br>- [Value-based dimension, unit, and quantity equations]                                                                                                                                             |
| **Feature Rich**             | - [Systems of Quantities]<br>- [Systems of Units]<br>- [Scalar, vector, and tensor quantities]<br>- [The affine space]<br>- [Natural units systems support]<br>- [Strong angular system]<br>- [Supports any unit's magnitude (huge, small, floating-point)]<br>- [Faster-than-lightspeed constants]<br>- [Highly adjustable text-output formatting] |
| **Easy to Extend**           | - [Each entity can be defined with a single line of code]<br>- [User can easily extend the systems with custom dimensions, quantities, and units]                                                                                                                                                                                                   |
| **Low Standardization Cost** | - Small number of predefined entities needed thanks to composability<br>- No external dependencies (assuming full C++20 support)<br>- No macros in the user interface (besides portability and standard-compliance issues)<br>- Possibility to be standardized as a [freestanding] part of the C++ Standard Library                                 |


[The affine space strong types]: ../users_guide/framework_basics/the_affine_space.md
[Compile-time checked conversions of quantities and units]: ../users_guide/framework_basics/systems_of_quantities.md#converting-between-quantities
[Unique support for many quantities of the same kind]: ../users_guide/framework_basics/systems_of_quantities.md#quantities-of-the-same-kind
[Type-safe equations on scalar, vector, and tensor quantities and their units]: ../users_guide/framework_basics/quantity_arithmetics.md
[Value-preserving conversions]: ../users_guide/framework_basics/value_conversions.md#value-preserving-conversions

[Optimized for readable compilation errors and great debugging experience]: ../users_guide/framework_basics/simple_and_typed_quantities.md#easy-to-understand-compilation-error-messages
[Efficient and composable way to specify a unit of choice]: ../users_guide/framework_basics/systems_of_units.md#units-compose
[Value-based dimension, unit, and quantity equations]: ../users_guide/framework_basics/interface_introduction.md#value-based-equations

[Systems of Quantities]: ../users_guide/framework_basics/systems_of_quantities.md
[Systems of Units]: ../users_guide/framework_basics/systems_of_units.md
[Scalar, vector, and tensor quantities]: ../users_guide/framework_basics/character_of_a_quantity.md
[The affine space]: ../users_guide/framework_basics/the_affine_space.md
[Natural units systems support]: ../users_guide/defining_systems/natural_units.md
[Strong angular system]: ../users_guide/defining_systems/strong_angular_system.md
[Supports any unit's magnitude (huge, small, floating-point)]: ../users_guide/framework_basics/systems_of_units.md#scaled-units
[Faster-than-lightspeed constants]: ../users_guide/framework_basics/faster_than_lightspeed_constants.md
[Highly adjustable text-output formatting]: ../users_guide/framework_basics/text_output.md

[Each entity can be defined with a single line of code]: ../users_guide/framework_basics/interface_introduction.md#new-style-of-definitions
[User can easily extend the systems with custom dimensions, quantities, and units]: ../users_guide/framework_basics/interface_introduction.md#new-style-of-definitions

[freestanding]: https://en.cppreference.com/w/cpp/freestanding
docs: initial V2 documenatation added 2023-06-21 10:55:18 +02:00			`# Introduction`

			`mp-units is a Modern C++ library that provides compile-time dimensional analysis and unit/quantity`
			`manipulation. The initial versions of the library were inspired by the`
			[`std::chrono::duration`](https://en.cppreference.com/w/cpp/chrono/duration)
			`but with each release, the interfaces diverged from the original to provide a better user`
			`experience.`

docs: admonition types usage fine tuned 2023-08-30 11:33:30 +02:00			`!!! info`
docs: ACCU 2023 talk referenced in the documentation 2023-08-16 06:41:54 +02:00
			`A brief introduction to the library's interfaces and the rationale for changes in the version 2.0`
			`of mp-units were provided in detail by [Mateusz Pusz](https://github.com/mpusz) in the`
			`["mp-units: Lessons Learned and a New C++ Library Design" talk at the ACCU 2023 conference](https://www.youtube.com/watch?v=l0rXdJfXLZc).`

docs: initial V2 documenatation added 2023-06-21 10:55:18 +02:00
			`## Open Source`

			`mp-units is Free and Open Source, with a permissive`
			`[MIT license](https://github.com/mpusz/mp-units/blob/master/LICENSE.md). Check out the source`
			`code and issue tracking (for questions and support, reporting bugs, suggesting feature requests`
			`and improvements) at <https://github.com/mpusz/mp-units>.`


			`## With the User's Experience in Mind`

			`Most of the critical design decisions in the library are dictated by the requirement of`
			`providing the best user experience possible. Other C++ physical units libraries are`
			`"famous" for their enormous and hard-to-understand error messages (one line of the error log often`
			`do not fit on one slide). The ultimate goal of mp-units is to improve this and make compile-time`
			`errors and debugging as easy and user-friendly as possible.`

			`To achieve this goal, several techniques are applied:`

			`- usage of C++20 concepts,`
docs: cross-page links fixed 2023-08-03 21:23:34 +02:00			`- [using strong types for framework entities (instead of type aliases)](../users_guide/framework_basics/interface_introduction.md#strong-types-instead-of-aliases),`
			`- [usage of expression templates to improve the readability of generated types](../users_guide/framework_basics/interface_introduction.md#expression-templates),`
docs: initial V2 documenatation added 2023-06-21 10:55:18 +02:00			`- limiting the number of template arguments to the bare minimum.`

docs: admonition types usage fine tuned 2023-08-30 11:33:30 +02:00			`!!! important`
docs: initial V2 documenatation added 2023-06-21 10:55:18 +02:00
			`In many generic C++ libraries compile-time errors do not happen often. It is hard to`
			break `std::string` or `std::vector` in a way it won't compile with a huge error
			`log. Physical Units libraries are different. **Generation of compile-time errors`
			`is the main reason to use such a library.**`


			`## Key Features`

docs: URLs added to the "Introduction" chapter 2023-07-07 20:43:06 +02:00			`\| Feature \| Description \|`
			`\|------------------------------\|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------\|`
			\| Safety \| - [The affine space strong types] (`quantity` and `quantity_point`)<br>- [Compile-time checked conversions of quantities and units]<br>- [Unique support for many quantities of the same kind]<br>- [Type-safe equations on scalar, vector, and tensor quantities and their units]<br>- [Value-preserving conversions] \|
			\| Performance \| - All the compile-time logic implemented as immediate (`consteval`) functions<br>- As fast or even faster than working with fundamental types<br>- No space size overhead needed to implement high-level abstractions \|
			`\| Great User Experience \| - [Optimized for readable compilation errors and great debugging experience]<br>- [Efficient and composable way to specify a unit of choice]<br>- [Value-based dimension, unit, and quantity equations] \|`
			`\| Feature Rich \| - [Systems of Quantities]<br>- [Systems of Units]<br>- [Scalar, vector, and tensor quantities]<br>- [The affine space]<br>- [Natural units systems support]<br>- [Strong angular system]<br>- [Supports any unit's magnitude (huge, small, floating-point)]<br>- [Faster-than-lightspeed constants]<br>- [Highly adjustable text-output formatting] \|`
			`\| Easy to Extend \| - [Each entity can be defined with a single line of code]<br>- [User can easily extend the systems with custom dimensions, quantities, and units] \|`
			`\| Low Standardization Cost \| - Small number of predefined entities needed thanks to composability<br>- No external dependencies (assuming full C++20 support)<br>- No macros in the user interface (besides portability and standard-compliance issues)<br>- Possibility to be standardized as a [freestanding] part of the C++ Standard Library \|`


docs: cross-page links fixed 2023-08-03 21:23:34 +02:00			`[The affine space strong types]: ../users_guide/framework_basics/the_affine_space.md`
			`[Compile-time checked conversions of quantities and units]: ../users_guide/framework_basics/systems_of_quantities.md#converting-between-quantities`
			`[Unique support for many quantities of the same kind]: ../users_guide/framework_basics/systems_of_quantities.md#quantities-of-the-same-kind`
			`[Type-safe equations on scalar, vector, and tensor quantities and their units]: ../users_guide/framework_basics/quantity_arithmetics.md`
			`[Value-preserving conversions]: ../users_guide/framework_basics/value_conversions.md#value-preserving-conversions`

			`[Optimized for readable compilation errors and great debugging experience]: ../users_guide/framework_basics/simple_and_typed_quantities.md#easy-to-understand-compilation-error-messages`
			`[Efficient and composable way to specify a unit of choice]: ../users_guide/framework_basics/systems_of_units.md#units-compose`
			`[Value-based dimension, unit, and quantity equations]: ../users_guide/framework_basics/interface_introduction.md#value-based-equations`

			`[Systems of Quantities]: ../users_guide/framework_basics/systems_of_quantities.md`
			`[Systems of Units]: ../users_guide/framework_basics/systems_of_units.md`
			`[Scalar, vector, and tensor quantities]: ../users_guide/framework_basics/character_of_a_quantity.md`
			`[The affine space]: ../users_guide/framework_basics/the_affine_space.md`
			`[Natural units systems support]: ../users_guide/defining_systems/natural_units.md`
			`[Strong angular system]: ../users_guide/defining_systems/strong_angular_system.md`
			`[Supports any unit's magnitude (huge, small, floating-point)]: ../users_guide/framework_basics/systems_of_units.md#scaled-units`
			`[Faster-than-lightspeed constants]: ../users_guide/framework_basics/faster_than_lightspeed_constants.md`
			`[Highly adjustable text-output formatting]: ../users_guide/framework_basics/text_output.md`

			`[Each entity can be defined with a single line of code]: ../users_guide/framework_basics/interface_introduction.md#new-style-of-definitions`
			`[User can easily extend the systems with custom dimensions, quantities, and units]: ../users_guide/framework_basics/interface_introduction.md#new-style-of-definitions`
docs: URLs added to the "Introduction" chapter 2023-07-07 20:43:06 +02:00
			`[freestanding]: https://en.cppreference.com/w/cpp/freestanding`