From dcc831954cb82a20a0bb5ca1459671917a35fa14 Mon Sep 17 00:00:00 2001 From: github-actions Date: Fri, 20 Jun 2025 15:24:19 +0000 Subject: [PATCH] Deployed 93f3be47 to HEAD with MkDocs 1.6.1 and mike 2.1.3 --- .../index.html | 5 +- HEAD/feed_json_updated.json | 2 +- HEAD/feed_rss_created.xml | 2 +- HEAD/feed_rss_updated.xml | 2 +- HEAD/search/search_index.json | 2 +- .../systems_of_quantities/index.html | 97 ++++++++++++------- 6 files changed, 70 insertions(+), 40 deletions(-) diff --git a/HEAD/blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/index.html b/HEAD/blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/index.html index 9ff4a261..89c20b8c 100644 --- a/HEAD/blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/index.html +++ b/HEAD/blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/index.html @@ -2726,12 +2726,13 @@ quantities of the same kind.

static_assert(explicitly_convertible(isq::width, isq::radius));

Explicit conversions are forced by passing the quantity to a call operator of a quantity_spec -type:

+type or by calling quantity's explicit constructor:

void foo(quantity<isq::height[m]> q);
 
quantity<isq::length[m]> q1 = 42 * m;
 quantity<isq::height[m]> q2 = isq::height(q1);  // explicit quantity conversion
-foo(isq::height(q1));                           // explicit quantity conversion
+quantity<isq::height[m]> q3(q1);                // direct initialization
+foo(isq::height(q1));                           // explicit quantity conversion
  • diff --git a/HEAD/feed_json_updated.json b/HEAD/feed_json_updated.json index efedd356..5eb1e1fc 100644 --- a/HEAD/feed_json_updated.json +++ b/HEAD/feed_json_updated.json @@ -1 +1 @@ -{"version": "https://jsonfeed.org/version/1", "title": "mp-units", "home_page_url": "https://mpusz.github.io/mp-units/HEAD/", "feed_url": "https://mpusz.github.io/mp-units/HEAD/feed_json_updated.json", "description": "The quantities and units library for C++", "icon": null, "authors": [{"name": "mp-units Team"}], "language": "en", "items": [{"id": "https://mpusz.github.io/mp-units/HEAD/blog/2025/06/16/introducing-absolute-quantities/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2025/06/16/introducing-absolute-quantities/", "title": "Introducing absolute quantities", "content_html": "

    Introducing absolute quantities

    \n

    This post introduces a new abstraction called an absolute quantity. It complements affine\nspace abstractions (point and delta) and will most probably be a new default in the library\nwhen we release V3.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/introducing-absolute-quantities.png", "date_modified": "2025-06-18T05:35:59+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Metrology"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2025/01/15/bringing-quantity-safety-to-the-next-level/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2025/01/15/bringing-quantity-safety-to-the-next-level/", "title": "Bringing Quantity-Safety To The Next Level", "content_html": "

    Bringing Quantity-Safety To The Next Level

    \n

    All quantities and units libraries need to be unit-safe. Most of the libraries on the market do\nthis correctly. Some of them are also dimension-safe, which adds another level of protection for\ntheir users.

    \n

    mp-units is probably the only library on the market that additionally is quantity-safe. This\ngives a new quality and possibilities. I've described the major idea behind it, implementation\ndetails, and benefits to the users in the series of posts about the International System of Quantities.

    \n

    However, this is only the beginning. We've always planned more and worked on the extensions in our\nfree time. In this post, I will describe:

    \n", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/bringing-quantity-safety-to-the-next-level.png", "date_modified": "2025-02-11T16:26:19+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Metrology"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/", "title": "International System of Quantities (ISQ): Part 4 - Implementing ISQ", "content_html": "

    International System of Quantities (ISQ): Part 4 - Implementing ISQ

    \n

    Up until now, we have introduced the International System of Quantities and described how we can\nmodel its main aspects. This article will present how to implement those models in a programming\nlanguage, and we will point out some of the first issues that stand in our way.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/isq-part-4-implemeting-isq.png", "date_modified": "2025-02-11T16:26:19+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Metrology"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/", "title": "International System of Quantities (ISQ): Part 6 - Challenges", "content_html": "

    International System of Quantities (ISQ): Part 6 - Challenges

    \n

    This article might be the last one from our series. This time, we will discuss the challenges and\nissues with modeling of the ISQ in software.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/isq-part-6-challenges.png", "date_modified": "2025-02-11T16:26:19+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Metrology"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/11/25/report-from-the-wroc%C5%82aw-2024-iso-c-committee-meeting/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/11/25/report-from-the-wroc%C5%82aw-2024-iso-c-committee-meeting/", "title": "Report from the Wroc\u0142aw 2024 ISO C++ Committee meeting", "content_html": "

    Report from the Wroc\u0142aw 2024 ISO C++ Committee meeting

    \n

    The Wroc\u0142aw 2024 meeting was another efficient step in the standardization of this library.\nWe've spent the entire day on the joint LEWGI and SG6 discussion and got lots of feedback.\nWe've also introduced std::fixed_string to LEWG for C++26.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/wroc\u0142aw-2024-report.png", "date_modified": "2024-11-29T12:45:06+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["WG21 Updates"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/", "title": "International System of Quantities (ISQ): Part 1 - Introduction", "content_html": "

    International System of Quantities (ISQ): Part 1 - Introduction

    \n

    This post starts a series of articles about the International System of Quantities (ISQ).\nIn this series, we will describe:

    \n", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/isq-part-1-introduction.png", "date_modified": "2024-11-11T22:37:29+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Metrology"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/", "title": "International System of Quantities (ISQ): Part 2 - Problems when ISQ is not used", "content_html": "

    International System of Quantities (ISQ): Part 2 - Problems when ISQ is not used

    \n

    This article is the next one in our series about the ISQ. After introducing the basic terms and\nsystems, this article will talk about the issues we face when we base the quantities and units\nlibrary on just units or dimensions.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/isq-part-2-problems-when-isq-is-not-used.png", "date_modified": "2024-11-11T22:37:29+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Metrology"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/", "title": "International System of Quantities (ISQ): Part 3 - Modeling ISQ", "content_html": "

    International System of Quantities (ISQ): Part 3 - Modeling ISQ

    \n

    The physical units libraries on the market typically only focus on modeling one or more systems\nof units. However, as we have learned, this is not the only system kind to model. Another,\nand maybe even more important, is a system of quantities. The most important example here is\nthe International System of Quantities (ISQ) defined by ISO/IEC 80000.

    \n

    This article continues our series about the International System of Quantities. This time, we will\nlearn about the main ideas behind the ISQ and describe how it can be modelled in a programming\nlanguage.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/isq-part-3-modeling-isq.png", "date_modified": "2024-11-11T22:37:29+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Metrology"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/", "title": "International System of Quantities (ISQ): Part 5 - Benefits", "content_html": "

    International System of Quantities (ISQ): Part 5 - Benefits

    \n

    In the previous articles, we introduced the International System of Quantities, described how we\ncan model and implement it in a programming language, and presented the issues of software that\ndoes not use such abstraction to implement a units library.

    \n

    Some of the issues raised in Part 2 of our series\nwere addressed in Part 3 already. This article will present\nhow our ISQ model elegantly addresses the remaining problems.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/isq-part-5-benefits.png", "date_modified": "2024-11-11T22:37:29+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Metrology"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/11/05/mp-units-240-released/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/11/05/mp-units-240-released/", "title": "mp-units 2.4.0 released!", "content_html": "

    mp-units 2.4.0 released!

    \n

    A new product version can be obtained from\nGitHub and\nConan.

    \n

    This release was unexpected. We planned a significant new feature to happen next, but while\npreparing for it, and also while writing API Reference documentation, we made so many vital fixes\nand improvements that we decided that they deserve a dedicated release first.

    \n

    This post describes the most significant improvements while a much longer list of the changes\nintroduced by the new version can be found in our Release Notes.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/2.4.0-released.png", "date_modified": "2024-11-05T18:46:13+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Releases"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/09/27/mp-units-230-released/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/09/27/mp-units-230-released/", "title": "mp-units 2.3.0 released!", "content_html": "

    mp-units 2.3.0 released!

    \n

    A new product version can be obtained from\nGitHub and\nConan.

    \n

    This release fine-tunes many key features of the library. This post describes the most interesting\nimprovements, while a much longer list of the changes introduced by the new version can be found in\nour Release Notes.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/2.3.0-released.png", "date_modified": "2024-09-30T17:11:10+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Releases"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2023/09/24/whats-new-in-mp-units-20/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2023/09/24/whats-new-in-mp-units-20/", "title": "What's new in mp-units 2.0?", "content_html": "

    What's new in mp-units 2.0?

    \n

    After a year of hard work, we've just released mp-units 2.0.0. It can be obtained from\nGitHub and\nConan.

    \n

    The list of the most significant changes introduced by the new version can be found in our\nRelease Notes. We will also describe some of them in this post.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/2.0.0-released.png", "date_modified": "2024-09-30T12:47:28+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Releases"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2023/12/09/mp-units-210-released/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2023/12/09/mp-units-210-released/", "title": "mp-units 2.1.0 released!", "content_html": "

    mp-units 2.1.0 released!

    \n

    A new product version can be obtained from\nGitHub and\nConan.

    \n

    The list of the most significant changes introduced by the new version can be found in our\nRelease Notes. We will also describe the most important of them\nin this post.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/2.1.0-released.png", "date_modified": "2024-09-30T12:47:28+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Releases"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/06/14/mp-units-220-released/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/06/14/mp-units-220-released/", "title": "mp-units 2.2.0 released!", "content_html": "

    mp-units 2.2.0 released!

    \n

    A new product version can be obtained from\nGitHub and\nConan.

    \n

    Among other features, this release provides long-awaited support for C++20 modules, redesigns and\nenhances text output formatting, and greatly simplifies quantity point usage. This post describes\nthose and a few other smaller interesting improvements, while a much longer list of the most\nsignificant changes introduced by the new version can be found in our\nRelease Notes.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/2.2.0-released.png", "date_modified": "2024-09-30T12:47:28+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Releases"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2023/11/12/report-from-the-kona-2023-iso-c-committee-meeting/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2023/11/12/report-from-the-kona-2023-iso-c-committee-meeting/", "title": "Report from the Kona 2023 ISO C++ Committee meeting", "content_html": "

    Report from the Kona 2023 ISO C++ Committee meeting

    \n

    Several groups in the ISO C++ Committee reviewed the P1935: A C++ Approach to Physical Units\nproposal in Belfast 2019 and Prague 2020. All those groups expressed interest in the potential\nstandardization of such a library and encouraged further work. The authors also got valuable\ninitial feedback that highly influenced the design of the V2 version of the mp-units library.

    \n

    In the following years, we scoped on getting more feedback from the production and design. This\nresulted in version 2 of the mp-units library that resolved many issues the users and Committee\nmembers raised. The features and interfaces of this version are close to being the best we can get\nwith the current version of the C++ language standard.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/kona-2023-report.png", "date_modified": "2024-09-30T12:47:28+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["WG21 Updates"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/07/02/report-from-the-st-louis-2024-iso-c-committee-meeting/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/07/02/report-from-the-st-louis-2024-iso-c-committee-meeting/", "title": "Report from the St. Louis 2024 ISO C++ Committee meeting", "content_html": "

    Report from the St. Louis 2024 ISO C++ Committee meeting

    \n

    We made significant progress in the standardization of this library during the ISO C++ Committee\nmeeting in St. Louis.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/st.louis-2024-report.png", "date_modified": "2024-09-30T12:47:28+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["WG21 Updates"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/04/15/report-from-the-tokyo-2024-iso-c-committee-meeting/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/04/15/report-from-the-tokyo-2024-iso-c-committee-meeting/", "title": "Report from the Tokyo 2024 ISO C++ Committee meeting", "content_html": "

    Report from the Tokyo 2024 ISO C++ Committee meeting

    \n

    The Tokyo 2024 meeting was a very important step in the standardization of this library. Several\nWG21 groups reviewed proposals, and the feedback was really good.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/tokyo-2024-report.png", "date_modified": "2024-09-30T12:47:28+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["WG21 Updates"]}]} \ No newline at end of file +{"version": "https://jsonfeed.org/version/1", "title": "mp-units", "home_page_url": "https://mpusz.github.io/mp-units/HEAD/", "feed_url": "https://mpusz.github.io/mp-units/HEAD/feed_json_updated.json", "description": "The quantities and units library for C++", "icon": null, "authors": [{"name": "mp-units Team"}], "language": "en", "items": [{"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/", "title": "International System of Quantities (ISQ): Part 3 - Modeling ISQ", "content_html": "

    International System of Quantities (ISQ): Part 3 - Modeling ISQ

    \n

    The physical units libraries on the market typically only focus on modeling one or more systems\nof units. However, as we have learned, this is not the only system kind to model. Another,\nand maybe even more important, is a system of quantities. The most important example here is\nthe International System of Quantities (ISQ) defined by ISO/IEC 80000.

    \n

    This article continues our series about the International System of Quantities. This time, we will\nlearn about the main ideas behind the ISQ and describe how it can be modelled in a programming\nlanguage.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/isq-part-3-modeling-isq.png", "date_modified": "2025-06-20T15:20:57+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Metrology"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2025/06/16/introducing-absolute-quantities/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2025/06/16/introducing-absolute-quantities/", "title": "Introducing absolute quantities", "content_html": "

    Introducing absolute quantities

    \n

    This post introduces a new abstraction called an absolute quantity. It complements affine\nspace abstractions (point and delta) and will most probably be a new default in the library\nwhen we release V3.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/introducing-absolute-quantities.png", "date_modified": "2025-06-18T05:35:59+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Metrology"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2025/01/15/bringing-quantity-safety-to-the-next-level/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2025/01/15/bringing-quantity-safety-to-the-next-level/", "title": "Bringing Quantity-Safety To The Next Level", "content_html": "

    Bringing Quantity-Safety To The Next Level

    \n

    All quantities and units libraries need to be unit-safe. Most of the libraries on the market do\nthis correctly. Some of them are also dimension-safe, which adds another level of protection for\ntheir users.

    \n

    mp-units is probably the only library on the market that additionally is quantity-safe. This\ngives a new quality and possibilities. I've described the major idea behind it, implementation\ndetails, and benefits to the users in the series of posts about the International System of Quantities.

    \n

    However, this is only the beginning. We've always planned more and worked on the extensions in our\nfree time. In this post, I will describe:

    \n", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/bringing-quantity-safety-to-the-next-level.png", "date_modified": "2025-02-11T16:26:19+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Metrology"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/", "title": "International System of Quantities (ISQ): Part 4 - Implementing ISQ", "content_html": "

    International System of Quantities (ISQ): Part 4 - Implementing ISQ

    \n

    Up until now, we have introduced the International System of Quantities and described how we can\nmodel its main aspects. This article will present how to implement those models in a programming\nlanguage, and we will point out some of the first issues that stand in our way.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/isq-part-4-implemeting-isq.png", "date_modified": "2025-02-11T16:26:19+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Metrology"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/", "title": "International System of Quantities (ISQ): Part 6 - Challenges", "content_html": "

    International System of Quantities (ISQ): Part 6 - Challenges

    \n

    This article might be the last one from our series. This time, we will discuss the challenges and\nissues with modeling of the ISQ in software.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/isq-part-6-challenges.png", "date_modified": "2025-02-11T16:26:19+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Metrology"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/11/25/report-from-the-wroc%C5%82aw-2024-iso-c-committee-meeting/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/11/25/report-from-the-wroc%C5%82aw-2024-iso-c-committee-meeting/", "title": "Report from the Wroc\u0142aw 2024 ISO C++ Committee meeting", "content_html": "

    Report from the Wroc\u0142aw 2024 ISO C++ Committee meeting

    \n

    The Wroc\u0142aw 2024 meeting was another efficient step in the standardization of this library.\nWe've spent the entire day on the joint LEWGI and SG6 discussion and got lots of feedback.\nWe've also introduced std::fixed_string to LEWG for C++26.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/wroc\u0142aw-2024-report.png", "date_modified": "2024-11-29T12:45:06+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["WG21 Updates"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/", "title": "International System of Quantities (ISQ): Part 1 - Introduction", "content_html": "

    International System of Quantities (ISQ): Part 1 - Introduction

    \n

    This post starts a series of articles about the International System of Quantities (ISQ).\nIn this series, we will describe:

    \n", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/isq-part-1-introduction.png", "date_modified": "2024-11-11T22:37:29+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Metrology"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/", "title": "International System of Quantities (ISQ): Part 2 - Problems when ISQ is not used", "content_html": "

    International System of Quantities (ISQ): Part 2 - Problems when ISQ is not used

    \n

    This article is the next one in our series about the ISQ. After introducing the basic terms and\nsystems, this article will talk about the issues we face when we base the quantities and units\nlibrary on just units or dimensions.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/isq-part-2-problems-when-isq-is-not-used.png", "date_modified": "2024-11-11T22:37:29+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Metrology"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/", "title": "International System of Quantities (ISQ): Part 5 - Benefits", "content_html": "

    International System of Quantities (ISQ): Part 5 - Benefits

    \n

    In the previous articles, we introduced the International System of Quantities, described how we\ncan model and implement it in a programming language, and presented the issues of software that\ndoes not use such abstraction to implement a units library.

    \n

    Some of the issues raised in Part 2 of our series\nwere addressed in Part 3 already. This article will present\nhow our ISQ model elegantly addresses the remaining problems.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/isq-part-5-benefits.png", "date_modified": "2024-11-11T22:37:29+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Metrology"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/11/05/mp-units-240-released/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/11/05/mp-units-240-released/", "title": "mp-units 2.4.0 released!", "content_html": "

    mp-units 2.4.0 released!

    \n

    A new product version can be obtained from\nGitHub and\nConan.

    \n

    This release was unexpected. We planned a significant new feature to happen next, but while\npreparing for it, and also while writing API Reference documentation, we made so many vital fixes\nand improvements that we decided that they deserve a dedicated release first.

    \n

    This post describes the most significant improvements while a much longer list of the changes\nintroduced by the new version can be found in our Release Notes.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/2.4.0-released.png", "date_modified": "2024-11-05T18:46:13+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Releases"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/09/27/mp-units-230-released/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/09/27/mp-units-230-released/", "title": "mp-units 2.3.0 released!", "content_html": "

    mp-units 2.3.0 released!

    \n

    A new product version can be obtained from\nGitHub and\nConan.

    \n

    This release fine-tunes many key features of the library. This post describes the most interesting\nimprovements, while a much longer list of the changes introduced by the new version can be found in\nour Release Notes.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/2.3.0-released.png", "date_modified": "2024-09-30T17:11:10+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Releases"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2023/09/24/whats-new-in-mp-units-20/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2023/09/24/whats-new-in-mp-units-20/", "title": "What's new in mp-units 2.0?", "content_html": "

    What's new in mp-units 2.0?

    \n

    After a year of hard work, we've just released mp-units 2.0.0. It can be obtained from\nGitHub and\nConan.

    \n

    The list of the most significant changes introduced by the new version can be found in our\nRelease Notes. We will also describe some of them in this post.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/2.0.0-released.png", "date_modified": "2024-09-30T12:47:28+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Releases"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2023/12/09/mp-units-210-released/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2023/12/09/mp-units-210-released/", "title": "mp-units 2.1.0 released!", "content_html": "

    mp-units 2.1.0 released!

    \n

    A new product version can be obtained from\nGitHub and\nConan.

    \n

    The list of the most significant changes introduced by the new version can be found in our\nRelease Notes. We will also describe the most important of them\nin this post.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/2.1.0-released.png", "date_modified": "2024-09-30T12:47:28+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Releases"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/06/14/mp-units-220-released/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/06/14/mp-units-220-released/", "title": "mp-units 2.2.0 released!", "content_html": "

    mp-units 2.2.0 released!

    \n

    A new product version can be obtained from\nGitHub and\nConan.

    \n

    Among other features, this release provides long-awaited support for C++20 modules, redesigns and\nenhances text output formatting, and greatly simplifies quantity point usage. This post describes\nthose and a few other smaller interesting improvements, while a much longer list of the most\nsignificant changes introduced by the new version can be found in our\nRelease Notes.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/2.2.0-released.png", "date_modified": "2024-09-30T12:47:28+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["Releases"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2023/11/12/report-from-the-kona-2023-iso-c-committee-meeting/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2023/11/12/report-from-the-kona-2023-iso-c-committee-meeting/", "title": "Report from the Kona 2023 ISO C++ Committee meeting", "content_html": "

    Report from the Kona 2023 ISO C++ Committee meeting

    \n

    Several groups in the ISO C++ Committee reviewed the P1935: A C++ Approach to Physical Units\nproposal in Belfast 2019 and Prague 2020. All those groups expressed interest in the potential\nstandardization of such a library and encouraged further work. The authors also got valuable\ninitial feedback that highly influenced the design of the V2 version of the mp-units library.

    \n

    In the following years, we scoped on getting more feedback from the production and design. This\nresulted in version 2 of the mp-units library that resolved many issues the users and Committee\nmembers raised. The features and interfaces of this version are close to being the best we can get\nwith the current version of the C++ language standard.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/kona-2023-report.png", "date_modified": "2024-09-30T12:47:28+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["WG21 Updates"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/07/02/report-from-the-st-louis-2024-iso-c-committee-meeting/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/07/02/report-from-the-st-louis-2024-iso-c-committee-meeting/", "title": "Report from the St. Louis 2024 ISO C++ Committee meeting", "content_html": "

    Report from the St. Louis 2024 ISO C++ Committee meeting

    \n

    We made significant progress in the standardization of this library during the ISO C++ Committee\nmeeting in St. Louis.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/st.louis-2024-report.png", "date_modified": "2024-09-30T12:47:28+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["WG21 Updates"]}, {"id": "https://mpusz.github.io/mp-units/HEAD/blog/2024/04/15/report-from-the-tokyo-2024-iso-c-committee-meeting/", "url": "https://mpusz.github.io/mp-units/HEAD/blog/2024/04/15/report-from-the-tokyo-2024-iso-c-committee-meeting/", "title": "Report from the Tokyo 2024 ISO C++ Committee meeting", "content_html": "

    Report from the Tokyo 2024 ISO C++ Committee meeting

    \n

    The Tokyo 2024 meeting was a very important step in the standardization of this library. Several\nWG21 groups reviewed proposals, and the feedback was really good.

    ", "image": "https://mpusz.github.io/mp-units/HEADassets/images/social/blog/posts/tokyo-2024-report.png", "date_modified": "2024-09-30T12:47:28+00:00", "authors": [{"name": "Mateusz Pusz"}], "tags": ["WG21 Updates"]}]} \ No newline at end of file diff --git a/HEAD/feed_rss_created.xml b/HEAD/feed_rss_created.xml index acdfa573..d71a3d58 100644 --- a/HEAD/feed_rss_created.xml +++ b/HEAD/feed_rss_created.xml @@ -1 +1 @@ - mp-unitsThe quantities and units library for C++https://mpusz.github.io/mp-units/HEAD/mp-units Teamhttps://github.com/mpusz/mp-unitsen Fri, 20 Jun 2025 09:00:50 -0000 Fri, 20 Jun 2025 09:00:50 -0000 1440 MkDocs RSS plugin - v1.17.3 None mp-unitshttps://mpusz.github.io/mp-units/HEAD/ Introducing absolute quantities Mateusz Pusz Metrology <h1>Introducing absolute quantities</h1><p>This post introduces a new abstraction called an absolute quantity. It complements affinespace abstractions (point and delta) and will most probably be a new default in the librarywhen we release V3.</p>https://mpusz.github.io/mp-units/HEAD/blog/2025/06/16/introducing-absolute-quantities/ Mon, 16 Jun 2025 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2025/06/16/introducing-absolute-quantities/ Bringing Quantity-Safety To The Next Level Mateusz Pusz Metrology <h1>Bringing Quantity-Safety To The Next Level</h1><p>All quantities and units libraries need to be unit-safe. Most of the libraries on the market dothis correctly. Some of them are also dimension-safe, which adds another level of protection fortheir users.</p><p><strong>mp-units</strong> is probably the only library on the market that additionally is quantity-safe. Thisgives a new quality and possibilities. I've described the major idea behind it, implementationdetails, and benefits to the users in the <a href="isq-part-5-benefits.md">series of posts about the International System of Quantities</a>.</p><p>However, this is only the beginning. We've always planned more and worked on the extensions in ourfree time. In this post, I will describe:</p><ul><li>What a quantity character is?</li><li>The importance of using proper representation types for the quantities.</li><li>The power of providing character-specific operations for the quantities.</li><li>Discuss implementation challenges and possible solutions.</li></ul>https://mpusz.github.io/mp-units/HEAD/blog/2025/01/15/bringing-quantity-safety-to-the-next-level/ Wed, 15 Jan 2025 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2025/01/15/bringing-quantity-safety-to-the-next-level/ Report from the Wrocław 2024 ISO C++ Committee meeting Mateusz Pusz WG21 Updates <h1>Report from the Wrocław 2024 ISO C++ Committee meeting</h1><p>The Wrocław 2024 meeting was another efficient step in the standardization of this library.We've spent the entire day on the joint LEWGI and SG6 discussion and got lots of feedback.We've also introduced <code>std::fixed_string</code> to LEWG for C++26.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/11/25/report-from-the-wroc%C5%82aw-2024-iso-c-committee-meeting/ Mon, 25 Nov 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/11/25/report-from-the-wroc%C5%82aw-2024-iso-c-committee-meeting/ International System of Quantities (ISQ): Part 6 - Challenges Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 6 - Challenges</h1><p>This article might be the last one from our series. This time, we will discuss the challenges andissues with modeling of the ISQ in software.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/ Mon, 11 Nov 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/ mp-units 2.4.0 released! Mateusz Pusz Releases <h1>mp-units 2.4.0 released!</h1><p><strong>A new product version can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.4.0">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.4.0">Conan</a>.</strong></p><p>This release was unexpected. We planned a significant new feature to happen next, but whilepreparing for it, and also while writing API Reference documentation, we made so many vital fixesand improvements that we decided that they deserve a dedicated release first.</p><p>This post describes the most significant improvements while a much longer list of the changesintroduced by the new version can be found in our <a href="../../release_notes.md#2.4.0">Release Notes</a>.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/11/05/mp-units-240-released/ Tue, 05 Nov 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/11/05/mp-units-240-released/ International System of Quantities (ISQ): Part 5 - Benefits Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 5 - Benefits</h1><p>In the previous articles, we introduced the International System of Quantities, described how wecan model and implement it in a programming language, and presented the issues of software thatdoes not use such abstraction to implement a units library.</p><p>Some of the issues raised in <a href="isq-part-2-problems-when-isq-is-not-used.md">Part 2</a> of our serieswere addressed in <a href="isq-part-3-modeling-isq.md">Part 3</a> already. This article will presenthow our ISQ model elegantly addresses the remaining problems.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/ Mon, 04 Nov 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/ International System of Quantities (ISQ): Part 4 - Implementing ISQ Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 4 - Implementing ISQ</h1><p>Up until now, we have introduced the International System of Quantities and described how we canmodel its main aspects. This article will present how to implement those models in a programminglanguage, and we will point out some of the first issues that stand in our way.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/ Mon, 28 Oct 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/ International System of Quantities (ISQ): Part 3 - Modeling ISQ Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 3 - Modeling ISQ</h1><p>The physical units libraries on the market typically only focus on modeling one or more systemsof units. However, as we have learned, this is not the only system kind to model. Another,and maybe even more important, is a system of quantities. The most important example here isthe International System of Quantities (ISQ) defined by ISO/IEC 80000.</p><p>This article continues our series about the International System of Quantities. This time, we willlearn about the main ideas behind the ISQ and describe how it can be modelled in a programminglanguage.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/ Mon, 21 Oct 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/ International System of Quantities (ISQ): Part 2 - Problems when ISQ is not used Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 2 - Problems when ISQ is not used</h1><p>This article is the next one in our series about the ISQ. After introducing the basic terms andsystems, this article will talk about the issues we face when we base the quantities and unitslibrary on just units or dimensions.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/ Mon, 14 Oct 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/ International System of Quantities (ISQ): Part 1 - Introduction Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 1 - Introduction</h1><p>This post starts a series of articles about the International System of Quantities (ISQ).In this series, we will describe:</p><ul><li>What is ISQ?</li><li>Which engineering problems does ISQ help to solve and how?</li><li>How to model and implement it in the programming language?</li><li>What is missing in the ISQ, and why is that a problem?</li></ul>https://mpusz.github.io/mp-units/HEAD/blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/ Mon, 07 Oct 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/ mp-units 2.3.0 released! Mateusz Pusz Releases <h1>mp-units 2.3.0 released!</h1><p><strong>A new product version can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.3.0">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.3.0">Conan</a>.</strong></p><p>This release fine-tunes many key features of the library. This post describes the most interestingimprovements, while a much longer list of the changes introduced by the new version can be found inour <a href="../../release_notes.md#2.3.0">Release Notes</a>.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/09/27/mp-units-230-released/ Fri, 27 Sep 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/09/27/mp-units-230-released/ Report from the St. Louis 2024 ISO C++ Committee meeting Mateusz Pusz WG21 Updates <h1>Report from the St. Louis 2024 ISO C++ Committee meeting</h1><p>We made significant progress in the standardization of this library during the ISO C++ Committeemeeting in St. Louis.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/07/02/report-from-the-st-louis-2024-iso-c-committee-meeting/ Tue, 02 Jul 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/07/02/report-from-the-st-louis-2024-iso-c-committee-meeting/ mp-units 2.2.0 released! Mateusz Pusz Releases <h1>mp-units 2.2.0 released!</h1><p><strong>A new product version can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.2.1">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.2.1">Conan</a>.</strong></p><p>Among other features, this release provides long-awaited support for C++20 modules, redesigns andenhances text output formatting, and greatly simplifies quantity point usage. This post describesthose and a few other smaller interesting improvements, while a much longer list of the mostsignificant changes introduced by the new version can be found in our<a href="../../release_notes.md#2.2.1">Release Notes</a>.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/06/14/mp-units-220-released/ Fri, 14 Jun 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/06/14/mp-units-220-released/ Report from the Tokyo 2024 ISO C++ Committee meeting Mateusz Pusz WG21 Updates <h1>Report from the Tokyo 2024 ISO C++ Committee meeting</h1><p>The Tokyo 2024 meeting was a very important step in the standardization of this library. SeveralWG21 groups reviewed proposals, and the feedback was really good.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/04/15/report-from-the-tokyo-2024-iso-c-committee-meeting/ Mon, 15 Apr 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/04/15/report-from-the-tokyo-2024-iso-c-committee-meeting/ mp-units 2.1.0 released! Mateusz Pusz Releases <h1>mp-units 2.1.0 released!</h1><p><strong>A new product version can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.1.0">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.1.0">Conan</a>.</strong></p><p>The list of the most significant changes introduced by the new version can be found in our<a href="../../release_notes.md#2.1.0">Release Notes</a>. We will also describe the most important of themin this post.</p>https://mpusz.github.io/mp-units/HEAD/blog/2023/12/09/mp-units-210-released/ Sat, 09 Dec 2023 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2023/12/09/mp-units-210-released/ Report from the Kona 2023 ISO C++ Committee meeting Mateusz Pusz WG21 Updates <h1>Report from the Kona 2023 ISO C++ Committee meeting</h1><p><strong>Several groups in the ISO C++ Committee reviewed the <a href="https://wg21.link/p1935">P1935: A C++ Approach to Physical Units</a>proposal in Belfast 2019 and Prague 2020. All those groups expressed interest in the potentialstandardization of such a library and encouraged further work. The authors also got valuableinitial feedback that highly influenced the design of the V2 version of the mp-units library.</strong></p><p>In the following years, we scoped on getting more feedback from the production and design. Thisresulted in version 2 of the <strong>mp-units</strong> library that resolved many issues the users and Committeemembers raised. The features and interfaces of this version are close to being the best we can getwith the current version of the C++ language standard.</p>https://mpusz.github.io/mp-units/HEAD/blog/2023/11/12/report-from-the-kona-2023-iso-c-committee-meeting/ Sun, 12 Nov 2023 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2023/11/12/report-from-the-kona-2023-iso-c-committee-meeting/ What's new in mp-units 2.0? Mateusz Pusz Releases <h1>What's new in mp-units 2.0?</h1><p><strong>After a year of hard work, we've just released mp-units 2.0.0. It can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.0.0">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.0.0">Conan</a>.</strong></p><p>The list of the most significant changes introduced by the new version can be found in our<a href="../../release_notes.md#2.0.0">Release Notes</a>. We will also describe some of them in this post.</p>https://mpusz.github.io/mp-units/HEAD/blog/2023/09/24/whats-new-in-mp-units-20/ Sun, 24 Sep 2023 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2023/09/24/whats-new-in-mp-units-20/ \ No newline at end of file + mp-unitsThe quantities and units library for C++https://mpusz.github.io/mp-units/HEAD/mp-units Teamhttps://github.com/mpusz/mp-unitsen Fri, 20 Jun 2025 15:24:15 -0000 Fri, 20 Jun 2025 15:24:15 -0000 1440 MkDocs RSS plugin - v1.17.3 None mp-unitshttps://mpusz.github.io/mp-units/HEAD/ Introducing absolute quantities Mateusz Pusz Metrology <h1>Introducing absolute quantities</h1><p>This post introduces a new abstraction called an absolute quantity. It complements affinespace abstractions (point and delta) and will most probably be a new default in the librarywhen we release V3.</p>https://mpusz.github.io/mp-units/HEAD/blog/2025/06/16/introducing-absolute-quantities/ Mon, 16 Jun 2025 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2025/06/16/introducing-absolute-quantities/ Bringing Quantity-Safety To The Next Level Mateusz Pusz Metrology <h1>Bringing Quantity-Safety To The Next Level</h1><p>All quantities and units libraries need to be unit-safe. Most of the libraries on the market dothis correctly. Some of them are also dimension-safe, which adds another level of protection fortheir users.</p><p><strong>mp-units</strong> is probably the only library on the market that additionally is quantity-safe. Thisgives a new quality and possibilities. I've described the major idea behind it, implementationdetails, and benefits to the users in the <a href="isq-part-5-benefits.md">series of posts about the International System of Quantities</a>.</p><p>However, this is only the beginning. We've always planned more and worked on the extensions in ourfree time. In this post, I will describe:</p><ul><li>What a quantity character is?</li><li>The importance of using proper representation types for the quantities.</li><li>The power of providing character-specific operations for the quantities.</li><li>Discuss implementation challenges and possible solutions.</li></ul>https://mpusz.github.io/mp-units/HEAD/blog/2025/01/15/bringing-quantity-safety-to-the-next-level/ Wed, 15 Jan 2025 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2025/01/15/bringing-quantity-safety-to-the-next-level/ Report from the Wrocław 2024 ISO C++ Committee meeting Mateusz Pusz WG21 Updates <h1>Report from the Wrocław 2024 ISO C++ Committee meeting</h1><p>The Wrocław 2024 meeting was another efficient step in the standardization of this library.We've spent the entire day on the joint LEWGI and SG6 discussion and got lots of feedback.We've also introduced <code>std::fixed_string</code> to LEWG for C++26.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/11/25/report-from-the-wroc%C5%82aw-2024-iso-c-committee-meeting/ Mon, 25 Nov 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/11/25/report-from-the-wroc%C5%82aw-2024-iso-c-committee-meeting/ International System of Quantities (ISQ): Part 6 - Challenges Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 6 - Challenges</h1><p>This article might be the last one from our series. This time, we will discuss the challenges andissues with modeling of the ISQ in software.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/ Mon, 11 Nov 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/ mp-units 2.4.0 released! Mateusz Pusz Releases <h1>mp-units 2.4.0 released!</h1><p><strong>A new product version can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.4.0">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.4.0">Conan</a>.</strong></p><p>This release was unexpected. We planned a significant new feature to happen next, but whilepreparing for it, and also while writing API Reference documentation, we made so many vital fixesand improvements that we decided that they deserve a dedicated release first.</p><p>This post describes the most significant improvements while a much longer list of the changesintroduced by the new version can be found in our <a href="../../release_notes.md#2.4.0">Release Notes</a>.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/11/05/mp-units-240-released/ Tue, 05 Nov 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/11/05/mp-units-240-released/ International System of Quantities (ISQ): Part 5 - Benefits Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 5 - Benefits</h1><p>In the previous articles, we introduced the International System of Quantities, described how wecan model and implement it in a programming language, and presented the issues of software thatdoes not use such abstraction to implement a units library.</p><p>Some of the issues raised in <a href="isq-part-2-problems-when-isq-is-not-used.md">Part 2</a> of our serieswere addressed in <a href="isq-part-3-modeling-isq.md">Part 3</a> already. This article will presenthow our ISQ model elegantly addresses the remaining problems.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/ Mon, 04 Nov 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/ International System of Quantities (ISQ): Part 4 - Implementing ISQ Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 4 - Implementing ISQ</h1><p>Up until now, we have introduced the International System of Quantities and described how we canmodel its main aspects. This article will present how to implement those models in a programminglanguage, and we will point out some of the first issues that stand in our way.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/ Mon, 28 Oct 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/ International System of Quantities (ISQ): Part 3 - Modeling ISQ Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 3 - Modeling ISQ</h1><p>The physical units libraries on the market typically only focus on modeling one or more systemsof units. However, as we have learned, this is not the only system kind to model. Another,and maybe even more important, is a system of quantities. The most important example here isthe International System of Quantities (ISQ) defined by ISO/IEC 80000.</p><p>This article continues our series about the International System of Quantities. This time, we willlearn about the main ideas behind the ISQ and describe how it can be modelled in a programminglanguage.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/ Mon, 21 Oct 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/ International System of Quantities (ISQ): Part 2 - Problems when ISQ is not used Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 2 - Problems when ISQ is not used</h1><p>This article is the next one in our series about the ISQ. After introducing the basic terms andsystems, this article will talk about the issues we face when we base the quantities and unitslibrary on just units or dimensions.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/ Mon, 14 Oct 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/ International System of Quantities (ISQ): Part 1 - Introduction Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 1 - Introduction</h1><p>This post starts a series of articles about the International System of Quantities (ISQ).In this series, we will describe:</p><ul><li>What is ISQ?</li><li>Which engineering problems does ISQ help to solve and how?</li><li>How to model and implement it in the programming language?</li><li>What is missing in the ISQ, and why is that a problem?</li></ul>https://mpusz.github.io/mp-units/HEAD/blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/ Mon, 07 Oct 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/ mp-units 2.3.0 released! Mateusz Pusz Releases <h1>mp-units 2.3.0 released!</h1><p><strong>A new product version can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.3.0">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.3.0">Conan</a>.</strong></p><p>This release fine-tunes many key features of the library. This post describes the most interestingimprovements, while a much longer list of the changes introduced by the new version can be found inour <a href="../../release_notes.md#2.3.0">Release Notes</a>.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/09/27/mp-units-230-released/ Fri, 27 Sep 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/09/27/mp-units-230-released/ Report from the St. Louis 2024 ISO C++ Committee meeting Mateusz Pusz WG21 Updates <h1>Report from the St. Louis 2024 ISO C++ Committee meeting</h1><p>We made significant progress in the standardization of this library during the ISO C++ Committeemeeting in St. Louis.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/07/02/report-from-the-st-louis-2024-iso-c-committee-meeting/ Tue, 02 Jul 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/07/02/report-from-the-st-louis-2024-iso-c-committee-meeting/ mp-units 2.2.0 released! Mateusz Pusz Releases <h1>mp-units 2.2.0 released!</h1><p><strong>A new product version can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.2.1">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.2.1">Conan</a>.</strong></p><p>Among other features, this release provides long-awaited support for C++20 modules, redesigns andenhances text output formatting, and greatly simplifies quantity point usage. This post describesthose and a few other smaller interesting improvements, while a much longer list of the mostsignificant changes introduced by the new version can be found in our<a href="../../release_notes.md#2.2.1">Release Notes</a>.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/06/14/mp-units-220-released/ Fri, 14 Jun 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/06/14/mp-units-220-released/ Report from the Tokyo 2024 ISO C++ Committee meeting Mateusz Pusz WG21 Updates <h1>Report from the Tokyo 2024 ISO C++ Committee meeting</h1><p>The Tokyo 2024 meeting was a very important step in the standardization of this library. SeveralWG21 groups reviewed proposals, and the feedback was really good.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/04/15/report-from-the-tokyo-2024-iso-c-committee-meeting/ Mon, 15 Apr 2024 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/04/15/report-from-the-tokyo-2024-iso-c-committee-meeting/ mp-units 2.1.0 released! Mateusz Pusz Releases <h1>mp-units 2.1.0 released!</h1><p><strong>A new product version can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.1.0">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.1.0">Conan</a>.</strong></p><p>The list of the most significant changes introduced by the new version can be found in our<a href="../../release_notes.md#2.1.0">Release Notes</a>. We will also describe the most important of themin this post.</p>https://mpusz.github.io/mp-units/HEAD/blog/2023/12/09/mp-units-210-released/ Sat, 09 Dec 2023 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2023/12/09/mp-units-210-released/ Report from the Kona 2023 ISO C++ Committee meeting Mateusz Pusz WG21 Updates <h1>Report from the Kona 2023 ISO C++ Committee meeting</h1><p><strong>Several groups in the ISO C++ Committee reviewed the <a href="https://wg21.link/p1935">P1935: A C++ Approach to Physical Units</a>proposal in Belfast 2019 and Prague 2020. All those groups expressed interest in the potentialstandardization of such a library and encouraged further work. The authors also got valuableinitial feedback that highly influenced the design of the V2 version of the mp-units library.</strong></p><p>In the following years, we scoped on getting more feedback from the production and design. Thisresulted in version 2 of the <strong>mp-units</strong> library that resolved many issues the users and Committeemembers raised. The features and interfaces of this version are close to being the best we can getwith the current version of the C++ language standard.</p>https://mpusz.github.io/mp-units/HEAD/blog/2023/11/12/report-from-the-kona-2023-iso-c-committee-meeting/ Sun, 12 Nov 2023 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2023/11/12/report-from-the-kona-2023-iso-c-committee-meeting/ What's new in mp-units 2.0? Mateusz Pusz Releases <h1>What's new in mp-units 2.0?</h1><p><strong>After a year of hard work, we've just released mp-units 2.0.0. It can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.0.0">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.0.0">Conan</a>.</strong></p><p>The list of the most significant changes introduced by the new version can be found in our<a href="../../release_notes.md#2.0.0">Release Notes</a>. We will also describe some of them in this post.</p>https://mpusz.github.io/mp-units/HEAD/blog/2023/09/24/whats-new-in-mp-units-20/ Sun, 24 Sep 2023 00:00:00 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2023/09/24/whats-new-in-mp-units-20/ \ No newline at end of file diff --git a/HEAD/feed_rss_updated.xml b/HEAD/feed_rss_updated.xml index 2326a238..cbab62ba 100644 --- a/HEAD/feed_rss_updated.xml +++ b/HEAD/feed_rss_updated.xml @@ -1 +1 @@ - mp-unitsThe quantities and units library for C++https://mpusz.github.io/mp-units/HEAD/mp-units Teamhttps://github.com/mpusz/mp-unitsen Fri, 20 Jun 2025 09:00:50 -0000 Fri, 20 Jun 2025 09:00:50 -0000 1440 MkDocs RSS plugin - v1.17.3 None mp-unitshttps://mpusz.github.io/mp-units/HEAD/ Introducing absolute quantities Mateusz Pusz Metrology <h1>Introducing absolute quantities</h1><p>This post introduces a new abstraction called an absolute quantity. It complements affinespace abstractions (point and delta) and will most probably be a new default in the librarywhen we release V3.</p>https://mpusz.github.io/mp-units/HEAD/blog/2025/06/16/introducing-absolute-quantities/ Wed, 18 Jun 2025 05:35:59 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2025/06/16/introducing-absolute-quantities/ Bringing Quantity-Safety To The Next Level Mateusz Pusz Metrology <h1>Bringing Quantity-Safety To The Next Level</h1><p>All quantities and units libraries need to be unit-safe. Most of the libraries on the market dothis correctly. Some of them are also dimension-safe, which adds another level of protection fortheir users.</p><p><strong>mp-units</strong> is probably the only library on the market that additionally is quantity-safe. Thisgives a new quality and possibilities. I've described the major idea behind it, implementationdetails, and benefits to the users in the <a href="isq-part-5-benefits.md">series of posts about the International System of Quantities</a>.</p><p>However, this is only the beginning. We've always planned more and worked on the extensions in ourfree time. In this post, I will describe:</p><ul><li>What a quantity character is?</li><li>The importance of using proper representation types for the quantities.</li><li>The power of providing character-specific operations for the quantities.</li><li>Discuss implementation challenges and possible solutions.</li></ul>https://mpusz.github.io/mp-units/HEAD/blog/2025/01/15/bringing-quantity-safety-to-the-next-level/ Tue, 11 Feb 2025 16:26:19 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2025/01/15/bringing-quantity-safety-to-the-next-level/ International System of Quantities (ISQ): Part 4 - Implementing ISQ Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 4 - Implementing ISQ</h1><p>Up until now, we have introduced the International System of Quantities and described how we canmodel its main aspects. This article will present how to implement those models in a programminglanguage, and we will point out some of the first issues that stand in our way.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/ Tue, 11 Feb 2025 16:26:19 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/ International System of Quantities (ISQ): Part 6 - Challenges Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 6 - Challenges</h1><p>This article might be the last one from our series. This time, we will discuss the challenges andissues with modeling of the ISQ in software.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/ Tue, 11 Feb 2025 16:26:19 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/ Report from the Wrocław 2024 ISO C++ Committee meeting Mateusz Pusz WG21 Updates <h1>Report from the Wrocław 2024 ISO C++ Committee meeting</h1><p>The Wrocław 2024 meeting was another efficient step in the standardization of this library.We've spent the entire day on the joint LEWGI and SG6 discussion and got lots of feedback.We've also introduced <code>std::fixed_string</code> to LEWG for C++26.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/11/25/report-from-the-wroc%C5%82aw-2024-iso-c-committee-meeting/ Fri, 29 Nov 2024 12:45:06 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/11/25/report-from-the-wroc%C5%82aw-2024-iso-c-committee-meeting/ International System of Quantities (ISQ): Part 1 - Introduction Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 1 - Introduction</h1><p>This post starts a series of articles about the International System of Quantities (ISQ).In this series, we will describe:</p><ul><li>What is ISQ?</li><li>Which engineering problems does ISQ help to solve and how?</li><li>How to model and implement it in the programming language?</li><li>What is missing in the ISQ, and why is that a problem?</li></ul>https://mpusz.github.io/mp-units/HEAD/blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/ Mon, 11 Nov 2024 22:37:29 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/ International System of Quantities (ISQ): Part 2 - Problems when ISQ is not used Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 2 - Problems when ISQ is not used</h1><p>This article is the next one in our series about the ISQ. After introducing the basic terms andsystems, this article will talk about the issues we face when we base the quantities and unitslibrary on just units or dimensions.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/ Mon, 11 Nov 2024 22:37:29 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/ International System of Quantities (ISQ): Part 3 - Modeling ISQ Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 3 - Modeling ISQ</h1><p>The physical units libraries on the market typically only focus on modeling one or more systemsof units. However, as we have learned, this is not the only system kind to model. Another,and maybe even more important, is a system of quantities. The most important example here isthe International System of Quantities (ISQ) defined by ISO/IEC 80000.</p><p>This article continues our series about the International System of Quantities. This time, we willlearn about the main ideas behind the ISQ and describe how it can be modelled in a programminglanguage.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/ Mon, 11 Nov 2024 22:37:29 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/ International System of Quantities (ISQ): Part 5 - Benefits Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 5 - Benefits</h1><p>In the previous articles, we introduced the International System of Quantities, described how wecan model and implement it in a programming language, and presented the issues of software thatdoes not use such abstraction to implement a units library.</p><p>Some of the issues raised in <a href="isq-part-2-problems-when-isq-is-not-used.md">Part 2</a> of our serieswere addressed in <a href="isq-part-3-modeling-isq.md">Part 3</a> already. This article will presenthow our ISQ model elegantly addresses the remaining problems.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/ Mon, 11 Nov 2024 22:37:29 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/ mp-units 2.4.0 released! Mateusz Pusz Releases <h1>mp-units 2.4.0 released!</h1><p><strong>A new product version can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.4.0">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.4.0">Conan</a>.</strong></p><p>This release was unexpected. We planned a significant new feature to happen next, but whilepreparing for it, and also while writing API Reference documentation, we made so many vital fixesand improvements that we decided that they deserve a dedicated release first.</p><p>This post describes the most significant improvements while a much longer list of the changesintroduced by the new version can be found in our <a href="../../release_notes.md#2.4.0">Release Notes</a>.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/11/05/mp-units-240-released/ Tue, 05 Nov 2024 18:46:13 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/11/05/mp-units-240-released/ mp-units 2.3.0 released! Mateusz Pusz Releases <h1>mp-units 2.3.0 released!</h1><p><strong>A new product version can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.3.0">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.3.0">Conan</a>.</strong></p><p>This release fine-tunes many key features of the library. This post describes the most interestingimprovements, while a much longer list of the changes introduced by the new version can be found inour <a href="../../release_notes.md#2.3.0">Release Notes</a>.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/09/27/mp-units-230-released/ Mon, 30 Sep 2024 17:11:10 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/09/27/mp-units-230-released/ What's new in mp-units 2.0? Mateusz Pusz Releases <h1>What's new in mp-units 2.0?</h1><p><strong>After a year of hard work, we've just released mp-units 2.0.0. It can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.0.0">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.0.0">Conan</a>.</strong></p><p>The list of the most significant changes introduced by the new version can be found in our<a href="../../release_notes.md#2.0.0">Release Notes</a>. We will also describe some of them in this post.</p>https://mpusz.github.io/mp-units/HEAD/blog/2023/09/24/whats-new-in-mp-units-20/ Mon, 30 Sep 2024 12:47:28 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2023/09/24/whats-new-in-mp-units-20/ mp-units 2.1.0 released! Mateusz Pusz Releases <h1>mp-units 2.1.0 released!</h1><p><strong>A new product version can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.1.0">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.1.0">Conan</a>.</strong></p><p>The list of the most significant changes introduced by the new version can be found in our<a href="../../release_notes.md#2.1.0">Release Notes</a>. We will also describe the most important of themin this post.</p>https://mpusz.github.io/mp-units/HEAD/blog/2023/12/09/mp-units-210-released/ Mon, 30 Sep 2024 12:47:28 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2023/12/09/mp-units-210-released/ mp-units 2.2.0 released! Mateusz Pusz Releases <h1>mp-units 2.2.0 released!</h1><p><strong>A new product version can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.2.1">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.2.1">Conan</a>.</strong></p><p>Among other features, this release provides long-awaited support for C++20 modules, redesigns andenhances text output formatting, and greatly simplifies quantity point usage. This post describesthose and a few other smaller interesting improvements, while a much longer list of the mostsignificant changes introduced by the new version can be found in our<a href="../../release_notes.md#2.2.1">Release Notes</a>.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/06/14/mp-units-220-released/ Mon, 30 Sep 2024 12:47:28 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/06/14/mp-units-220-released/ Report from the Kona 2023 ISO C++ Committee meeting Mateusz Pusz WG21 Updates <h1>Report from the Kona 2023 ISO C++ Committee meeting</h1><p><strong>Several groups in the ISO C++ Committee reviewed the <a href="https://wg21.link/p1935">P1935: A C++ Approach to Physical Units</a>proposal in Belfast 2019 and Prague 2020. All those groups expressed interest in the potentialstandardization of such a library and encouraged further work. The authors also got valuableinitial feedback that highly influenced the design of the V2 version of the mp-units library.</strong></p><p>In the following years, we scoped on getting more feedback from the production and design. Thisresulted in version 2 of the <strong>mp-units</strong> library that resolved many issues the users and Committeemembers raised. The features and interfaces of this version are close to being the best we can getwith the current version of the C++ language standard.</p>https://mpusz.github.io/mp-units/HEAD/blog/2023/11/12/report-from-the-kona-2023-iso-c-committee-meeting/ Mon, 30 Sep 2024 12:47:28 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2023/11/12/report-from-the-kona-2023-iso-c-committee-meeting/ Report from the St. Louis 2024 ISO C++ Committee meeting Mateusz Pusz WG21 Updates <h1>Report from the St. Louis 2024 ISO C++ Committee meeting</h1><p>We made significant progress in the standardization of this library during the ISO C++ Committeemeeting in St. Louis.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/07/02/report-from-the-st-louis-2024-iso-c-committee-meeting/ Mon, 30 Sep 2024 12:47:28 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/07/02/report-from-the-st-louis-2024-iso-c-committee-meeting/ Report from the Tokyo 2024 ISO C++ Committee meeting Mateusz Pusz WG21 Updates <h1>Report from the Tokyo 2024 ISO C++ Committee meeting</h1><p>The Tokyo 2024 meeting was a very important step in the standardization of this library. SeveralWG21 groups reviewed proposals, and the feedback was really good.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/04/15/report-from-the-tokyo-2024-iso-c-committee-meeting/ Mon, 30 Sep 2024 12:47:28 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/04/15/report-from-the-tokyo-2024-iso-c-committee-meeting/ \ No newline at end of file + mp-unitsThe quantities and units library for C++https://mpusz.github.io/mp-units/HEAD/mp-units Teamhttps://github.com/mpusz/mp-unitsen Fri, 20 Jun 2025 15:24:15 -0000 Fri, 20 Jun 2025 15:24:15 -0000 1440 MkDocs RSS plugin - v1.17.3 None mp-unitshttps://mpusz.github.io/mp-units/HEAD/ International System of Quantities (ISQ): Part 3 - Modeling ISQ Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 3 - Modeling ISQ</h1><p>The physical units libraries on the market typically only focus on modeling one or more systemsof units. However, as we have learned, this is not the only system kind to model. Another,and maybe even more important, is a system of quantities. The most important example here isthe International System of Quantities (ISQ) defined by ISO/IEC 80000.</p><p>This article continues our series about the International System of Quantities. This time, we willlearn about the main ideas behind the ISQ and describe how it can be modelled in a programminglanguage.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/ Fri, 20 Jun 2025 15:20:57 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/ Introducing absolute quantities Mateusz Pusz Metrology <h1>Introducing absolute quantities</h1><p>This post introduces a new abstraction called an absolute quantity. It complements affinespace abstractions (point and delta) and will most probably be a new default in the librarywhen we release V3.</p>https://mpusz.github.io/mp-units/HEAD/blog/2025/06/16/introducing-absolute-quantities/ Wed, 18 Jun 2025 05:35:59 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2025/06/16/introducing-absolute-quantities/ Bringing Quantity-Safety To The Next Level Mateusz Pusz Metrology <h1>Bringing Quantity-Safety To The Next Level</h1><p>All quantities and units libraries need to be unit-safe. Most of the libraries on the market dothis correctly. Some of them are also dimension-safe, which adds another level of protection fortheir users.</p><p><strong>mp-units</strong> is probably the only library on the market that additionally is quantity-safe. Thisgives a new quality and possibilities. I've described the major idea behind it, implementationdetails, and benefits to the users in the <a href="isq-part-5-benefits.md">series of posts about the International System of Quantities</a>.</p><p>However, this is only the beginning. We've always planned more and worked on the extensions in ourfree time. In this post, I will describe:</p><ul><li>What a quantity character is?</li><li>The importance of using proper representation types for the quantities.</li><li>The power of providing character-specific operations for the quantities.</li><li>Discuss implementation challenges and possible solutions.</li></ul>https://mpusz.github.io/mp-units/HEAD/blog/2025/01/15/bringing-quantity-safety-to-the-next-level/ Tue, 11 Feb 2025 16:26:19 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2025/01/15/bringing-quantity-safety-to-the-next-level/ International System of Quantities (ISQ): Part 4 - Implementing ISQ Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 4 - Implementing ISQ</h1><p>Up until now, we have introduced the International System of Quantities and described how we canmodel its main aspects. This article will present how to implement those models in a programminglanguage, and we will point out some of the first issues that stand in our way.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/ Tue, 11 Feb 2025 16:26:19 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/ International System of Quantities (ISQ): Part 6 - Challenges Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 6 - Challenges</h1><p>This article might be the last one from our series. This time, we will discuss the challenges andissues with modeling of the ISQ in software.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/ Tue, 11 Feb 2025 16:26:19 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/ Report from the Wrocław 2024 ISO C++ Committee meeting Mateusz Pusz WG21 Updates <h1>Report from the Wrocław 2024 ISO C++ Committee meeting</h1><p>The Wrocław 2024 meeting was another efficient step in the standardization of this library.We've spent the entire day on the joint LEWGI and SG6 discussion and got lots of feedback.We've also introduced <code>std::fixed_string</code> to LEWG for C++26.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/11/25/report-from-the-wroc%C5%82aw-2024-iso-c-committee-meeting/ Fri, 29 Nov 2024 12:45:06 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/11/25/report-from-the-wroc%C5%82aw-2024-iso-c-committee-meeting/ International System of Quantities (ISQ): Part 1 - Introduction Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 1 - Introduction</h1><p>This post starts a series of articles about the International System of Quantities (ISQ).In this series, we will describe:</p><ul><li>What is ISQ?</li><li>Which engineering problems does ISQ help to solve and how?</li><li>How to model and implement it in the programming language?</li><li>What is missing in the ISQ, and why is that a problem?</li></ul>https://mpusz.github.io/mp-units/HEAD/blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/ Mon, 11 Nov 2024 22:37:29 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/ International System of Quantities (ISQ): Part 2 - Problems when ISQ is not used Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 2 - Problems when ISQ is not used</h1><p>This article is the next one in our series about the ISQ. After introducing the basic terms andsystems, this article will talk about the issues we face when we base the quantities and unitslibrary on just units or dimensions.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/ Mon, 11 Nov 2024 22:37:29 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/ International System of Quantities (ISQ): Part 5 - Benefits Mateusz Pusz Metrology <h1>International System of Quantities (ISQ): Part 5 - Benefits</h1><p>In the previous articles, we introduced the International System of Quantities, described how wecan model and implement it in a programming language, and presented the issues of software thatdoes not use such abstraction to implement a units library.</p><p>Some of the issues raised in <a href="isq-part-2-problems-when-isq-is-not-used.md">Part 2</a> of our serieswere addressed in <a href="isq-part-3-modeling-isq.md">Part 3</a> already. This article will presenthow our ISQ model elegantly addresses the remaining problems.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/ Mon, 11 Nov 2024 22:37:29 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/ mp-units 2.4.0 released! Mateusz Pusz Releases <h1>mp-units 2.4.0 released!</h1><p><strong>A new product version can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.4.0">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.4.0">Conan</a>.</strong></p><p>This release was unexpected. We planned a significant new feature to happen next, but whilepreparing for it, and also while writing API Reference documentation, we made so many vital fixesand improvements that we decided that they deserve a dedicated release first.</p><p>This post describes the most significant improvements while a much longer list of the changesintroduced by the new version can be found in our <a href="../../release_notes.md#2.4.0">Release Notes</a>.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/11/05/mp-units-240-released/ Tue, 05 Nov 2024 18:46:13 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/11/05/mp-units-240-released/ mp-units 2.3.0 released! Mateusz Pusz Releases <h1>mp-units 2.3.0 released!</h1><p><strong>A new product version can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.3.0">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.3.0">Conan</a>.</strong></p><p>This release fine-tunes many key features of the library. This post describes the most interestingimprovements, while a much longer list of the changes introduced by the new version can be found inour <a href="../../release_notes.md#2.3.0">Release Notes</a>.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/09/27/mp-units-230-released/ Mon, 30 Sep 2024 17:11:10 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/09/27/mp-units-230-released/ What's new in mp-units 2.0? Mateusz Pusz Releases <h1>What's new in mp-units 2.0?</h1><p><strong>After a year of hard work, we've just released mp-units 2.0.0. It can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.0.0">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.0.0">Conan</a>.</strong></p><p>The list of the most significant changes introduced by the new version can be found in our<a href="../../release_notes.md#2.0.0">Release Notes</a>. We will also describe some of them in this post.</p>https://mpusz.github.io/mp-units/HEAD/blog/2023/09/24/whats-new-in-mp-units-20/ Mon, 30 Sep 2024 12:47:28 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2023/09/24/whats-new-in-mp-units-20/ mp-units 2.1.0 released! Mateusz Pusz Releases <h1>mp-units 2.1.0 released!</h1><p><strong>A new product version can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.1.0">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.1.0">Conan</a>.</strong></p><p>The list of the most significant changes introduced by the new version can be found in our<a href="../../release_notes.md#2.1.0">Release Notes</a>. We will also describe the most important of themin this post.</p>https://mpusz.github.io/mp-units/HEAD/blog/2023/12/09/mp-units-210-released/ Mon, 30 Sep 2024 12:47:28 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2023/12/09/mp-units-210-released/ mp-units 2.2.0 released! Mateusz Pusz Releases <h1>mp-units 2.2.0 released!</h1><p><strong>A new product version can be obtained from<a href="https://github.com/mpusz/mp-units/releases/tag/v2.2.1">GitHub</a> and<a href="https://conan.io/center/recipes/mp-units?version=2.2.1">Conan</a>.</strong></p><p>Among other features, this release provides long-awaited support for C++20 modules, redesigns andenhances text output formatting, and greatly simplifies quantity point usage. This post describesthose and a few other smaller interesting improvements, while a much longer list of the mostsignificant changes introduced by the new version can be found in our<a href="../../release_notes.md#2.2.1">Release Notes</a>.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/06/14/mp-units-220-released/ Mon, 30 Sep 2024 12:47:28 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/06/14/mp-units-220-released/ Report from the Kona 2023 ISO C++ Committee meeting Mateusz Pusz WG21 Updates <h1>Report from the Kona 2023 ISO C++ Committee meeting</h1><p><strong>Several groups in the ISO C++ Committee reviewed the <a href="https://wg21.link/p1935">P1935: A C++ Approach to Physical Units</a>proposal in Belfast 2019 and Prague 2020. All those groups expressed interest in the potentialstandardization of such a library and encouraged further work. The authors also got valuableinitial feedback that highly influenced the design of the V2 version of the mp-units library.</strong></p><p>In the following years, we scoped on getting more feedback from the production and design. Thisresulted in version 2 of the <strong>mp-units</strong> library that resolved many issues the users and Committeemembers raised. The features and interfaces of this version are close to being the best we can getwith the current version of the C++ language standard.</p>https://mpusz.github.io/mp-units/HEAD/blog/2023/11/12/report-from-the-kona-2023-iso-c-committee-meeting/ Mon, 30 Sep 2024 12:47:28 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2023/11/12/report-from-the-kona-2023-iso-c-committee-meeting/ Report from the St. Louis 2024 ISO C++ Committee meeting Mateusz Pusz WG21 Updates <h1>Report from the St. Louis 2024 ISO C++ Committee meeting</h1><p>We made significant progress in the standardization of this library during the ISO C++ Committeemeeting in St. Louis.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/07/02/report-from-the-st-louis-2024-iso-c-committee-meeting/ Mon, 30 Sep 2024 12:47:28 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/07/02/report-from-the-st-louis-2024-iso-c-committee-meeting/ Report from the Tokyo 2024 ISO C++ Committee meeting Mateusz Pusz WG21 Updates <h1>Report from the Tokyo 2024 ISO C++ Committee meeting</h1><p>The Tokyo 2024 meeting was a very important step in the standardization of this library. SeveralWG21 groups reviewed proposals, and the feedback was really good.</p>https://mpusz.github.io/mp-units/HEAD/blog/2024/04/15/report-from-the-tokyo-2024-iso-c-committee-meeting/ Mon, 30 Sep 2024 12:47:28 +0000mp-unitshttps://mpusz.github.io/mp-units/HEAD/blog/2024/04/15/report-from-the-tokyo-2024-iso-c-committee-meeting/ \ No newline at end of file diff --git a/HEAD/search/search_index.json b/HEAD/search/search_index.json index 09b22208..d0150638 100644 --- a/HEAD/search/search_index.json +++ b/HEAD/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome to mp-units!","text":"

    mp-units is a compile-time enabled feature-rich Modern C++ modular/header-only library that provides compile-time dimensional analysis and unit/quantity manipulation. Its key strengths include safety, performance, and developer experience.

    It is the first library on the market that, besides being unit-safe and dimension-safe, is also quantity-safe.

    The library source code is hosted on GitHub with a permissive MIT license.

    Supported compilers

    This library tries to provide the best user experience possible with the C++ language. To achieve that, it extensively uses the latest C++ language features.

    Even though the library benefits from the latest C++ versions (if available), C++20 is enough to compile and use all of the library's functionality.

    Please refer to C++ compiler support chapter for more details.

    C++ modulesHeader files 
    #include <iostream>\n#include <print>\nimport mp_units;\n\nusing namespace mp_units;\n\ninline constexpr struct smoot final : named_unit<\"smoot\", mag<67> * usc::inch> {} smoot;\n\nint main()\n{\n  constexpr quantity dist = 364.4 * smoot;\n  std::println(\"Harvard Bridge length = {::N[.1f]} ({::N[.1f]}, {::N[.2f]}) \u00b1 1 \u03b5ar\",\n               dist, dist.in(usc::foot), dist.in(si::metre));\n}\n
    #include <mp-units/systems/si.h>\n#include <mp-units/systems/usc.h>\n#include <print>\n\nusing namespace mp_units;\n\ninline constexpr struct smoot final : named_unit<\"smoot\", mag<67> * usc::inch> {} smoot;\n\nint main()\n{\n  constexpr quantity dist = 364.4 * smoot;\n  std::println(\"Harvard Bridge length = {::N[.1f]} ({::N[.1f]}, {::N[.2f]}) \u00b1 1 \u03b5ar\",\n               dist, dist.in(usc::foot), dist.in(si::metre));\n}\n

    Output:

    Harvard Bridge length = 364.4 smoot (2034.6 ft, 620.14 m) \u00b1 1 \u03b5ar\n

    Try it on Compiler Explorer

    What is smoot?

    The smoot (/\u02c8smu\u02d0t/) is a nonstandard unit of length created as part of an MIT fraternity prank. It is named after Oliver R. Smoot, a fraternity pledge to Lambda Chi Alpha, who, in October 1958, lay on the Harvard Bridge (between Boston and Cambridge, Massachusetts) and was used by his fraternity brothers to measure the length of the bridge.

    One smoot equals Oliver Smoot's height at the time of the prank (five feet and seven inches). The bridge's length was measured to be 364.4 smoots plus or minus one ear, with the \"plus or minus\" intended to express the measurement uncertainty.

    Oliver Smoot graduated from MIT with the class of 1962, became a lawyer, and later became chairman of the American National Standards Institute (ANSI) and president of the International Organization for Standardization (ISO).

    More on the smoot unit of length can be found at https://en.wikipedia.org/wiki/Smoot.

    Important: Help needed!

    The mp-units library might be the subject of ISO standardization for C++29. More on this can be found in the following ISO C++ proposals:

    We are actively looking for parties interested in field-trialing the library.

    "},{"location":"api_reference/","title":"API Reference - mp-units","text":""},{"location":"release_notes/","title":"Release Notes","text":""},{"location":"release_notes/#mp-units","title":"mp-units","text":""},{"location":"release_notes/#2.5.0","title":"2.5.0 WIP","text":""},{"location":"release_notes/#2.4.0","title":"2.4.0 November 5, 2024","text":""},{"location":"release_notes/#2.3.0","title":"2.3.0 September 27, 2024","text":""},{"location":"release_notes/#2.2.1","title":"2.2.1 July 3, 2024","text":""},{"location":"release_notes/#2.2.0","title":"2.2.0 June 14, 2024","text":""},{"location":"release_notes/#2.1.1","title":"2.1.1 May 16, 2024","text":""},{"location":"release_notes/#2.1.0","title":"2.1.0 December 9, 2023","text":""},{"location":"release_notes/#2.0.0","title":"2.0.0 September 24, 2023","text":""},{"location":"release_notes/#0.8.0","title":"0.8.0 June 14, 2023","text":""},{"location":"release_notes/#0.7.0","title":"0.7.0 May 11, 2021","text":""},{"location":"release_notes/#0.6.0","title":"0.6.0 September 13, 2020","text":""},{"location":"release_notes/#0.5.0","title":"0.5.0 May 17, 2020","text":"

    Many thanks to GitHub users @oschonrock, @kwikius, and @i-ky for their support in drafting a new library design.

    "},{"location":"release_notes/#0.4.0","title":"0.4.0 Nov 17, 2019","text":""},{"location":"release_notes/#0.3.1","title":"0.3.1 Sep 18, 2019","text":""},{"location":"release_notes/#0.3.0","title":"0.3.0 Sep 16, 2019","text":""},{"location":"release_notes/#0.2.0","title":"0.2.0 July 18, 2019","text":""},{"location":"release_notes/#0.1.0","title":"0.1.0 May 18, 2019","text":""},{"location":"appendix/glossary/","title":"Glossary","text":""},{"location":"appendix/glossary/#iso-definitions","title":"ISO definitions","text":"

    Note

    The ISO terms provided below are only a few of many defined in the ISO/IEC Guide 99.

    quantity kind of quantity, kind system of quantities base quantity derived quantity International System of Quantities, ISQ quantity dimension, dimension of a quantity, dimension quantity of dimension one, dimensionless quantity measurement unit, unit of measurement, unit base unit derived unit coherent derived unit system of units coherent system of units off-system measurement unit, off-system unit International System of Units, SI quantity value, value of a quantity, value numerical quantity value, numerical value of a quantity, numerical value quantity equation unit equation numerical value equation, numerical quantity value equation "},{"location":"appendix/glossary/#other-definitions","title":"Other definitions","text":"

    Info

    The below terms extend the official ISO glossary and are commonly referred to by the mp-units library.

    base dimension derived dimension dimension equation quantity kind hierarchy, quantity hierarchy quantity character, character of a quantity, character

    ISO 80000-1_2009

    In deriving the dimension of a quantity, no account is taken of its scalar, vector, or tensor character.

    quantity specification, quantity_spec unit with an associated quantity, associated unit quantity reference, reference canonical representation of a unit, canonical unit reference unit

    See canonical representation of a unit

    absolute quantity point origin, absolute point origin relative quantity point origin, relative point origin quantity point origin, point origin quantity point, absolute quantity "},{"location":"appendix/references/","title":"References","text":"ISO80000

    ISO 80000-1:2009(E) \"Quantities and units \u2014 Part 1: General\", International Organization for Standardization.

    Quincey \"Angles in the SI: a detailed proposal for solving the problem, Quincey, Paul (1 October 2021). SIBrochure

    The International System of Units (SI), International Bureau of Weights and Measures (20 May 2019), ISBN 978-92-822-2272-0.

    "},{"location":"blog/","title":"Blog","text":""},{"location":"blog/2023/09/24/whats-new-in-mp-units-20/","title":"What's new in mp-units 2.0?","text":"

    After a year of hard work, we've just released mp-units 2.0.0. It can be obtained from GitHub and Conan.

    The list of the most significant changes introduced by the new version can be found in our Release Notes. We will also describe some of them in this post.

    "},{"location":"blog/2023/09/24/whats-new-in-mp-units-20/#why-20-if-10-was-never-released","title":"Why 2.0 if 1.0 was never released?","text":"

    Version 2 of the mp-units project is a huge change and a new quality for the users. We did not want to pretend that 2.0 is an evolutionary upgrade of the previous version of the project. It feels like a different product.

    We could start a new repo named \"mp-units-v2\" similarly to range-v3 but we decided not to go this path. We kept the same repo and made the scope of the changes and potential breakage explicit with a drastic bump in the project version.

    "},{"location":"blog/2023/09/24/whats-new-in-mp-units-20/#what-has-changed","title":"What has changed?","text":"

    The answer is \"nearly everything\". The whole library and its documentation were rewritten nearly from scratch.

    Here are the significant changes that the users can observe:

    "},{"location":"blog/2023/09/24/whats-new-in-mp-units-20/#what-is-gone","title":"What is gone?","text":"

    Some cornerstones of the initial design did not prove in practice and were removed while we moved to version 2.

    "},{"location":"blog/2023/09/24/whats-new-in-mp-units-20/#the-downcasting-facility","title":"The downcasting facility","text":"

    The first and the most important of such features was removing the downcasting facility. This feature is still a powerful metaprogramming technique that allows users to map long class template instantiations to nicely named, short, and easy-to-understand user's strong types.

    Such mapping works perfectly fine for 1-to-1 relationships. However, we often deal with N-to-1 connections in the quantities and units domain. Here are only a few such examples:

    In the above examples, multiple entities \"wanted\" to register different names for identical class template instantiations, resulting in compile-time errors. We had to invent some hacks and workarounds to make it work, but we were never satisfied with the outcome.

    Additionally, this facility could easily lead to ODR violations or provide different results depending on which header files were included in the translation units. This was too vulnerable to be considered a good practice here.

    "},{"location":"blog/2023/09/24/whats-new-in-mp-units-20/#no-udls-anymore","title":"No UDLs anymore","text":"

    Over the years, we have learned that UDLs are not a good solution. More information on this subject can be found in the Why don't we use UDLs to create quantities? chapter.

    "},{"location":"blog/2023/09/24/whats-new-in-mp-units-20/#no-construction-of-a-quantity-from-a-raw-value","title":"No construction of a quantity from a raw value","text":"

    To improve safety, we no longer allow the construction of quantities from raw values. In the new design, we always need to explicitly specify a unit to create a quantity:

    quantity q1 = 42 * m;\nquantity<si::metre> = 2 * km;\nquantity q3(42, si::metre);\n

    The previous approach was reported to be error-prone under maintenance. More on this subject can be found in the Why can't I create a quantity by passing a number to a constructor? chapter.

    "},{"location":"blog/2023/09/24/whats-new-in-mp-units-20/#new-look-and-feel","title":"New look and feel","text":"

    Here is a concise example showing you the new look and feel of the library:

    #include <mp-units/format.h>\n#include <mp-units/systems/isq/isq.h>\n#include <mp-units/systems/si/si.h>\n#include <format>\n\nusing namespace mp_units;\nusing namespace mp_units::si::unit_symbols;\n\nquantity<isq::speed[m / s]> avg_speed(quantity<si::metre> d,\n                                      quantity<si::second> t)\n{ return d / t; }\n\nint main()\n{\n  auto speed = avg_speed(220 * km, 2 * h);\n  std::println(\"{}\", speed);  // 30.5556 m/s\n}\n

    All of the changes we provided, although breaking ones, resulted in much better, easier, and safer abstractions. These offer a new quantity on the market and hopefully will be appreciated by our users.

    Please check our new documentation to learn about the latest version of the project and find out how to benefit from all the new cool stuff we have here.

    "},{"location":"blog/2023/12/09/mp-units-210-released/","title":"mp-units 2.1.0 released!","text":"

    A new product version can be obtained from GitHub and Conan.

    The list of the most significant changes introduced by the new version can be found in our Release Notes. We will also describe the most important of them in this post.

    "},{"location":"blog/2023/12/09/mp-units-210-released/#no-more-parenthesis-while-creating-quantities-with-derived-units","title":"No more parenthesis while creating quantities with derived units","text":"

    The V2 design introduced a way to create a quantity by multiplying a raw value and a unit:

    quantity q1 = 42 * m;\n

    However, this meant that when we wanted to create a quantity having a derived unit, we had to put parenthesis around the unit equation or create a custom value of the named unit:

    quantity q2 = 60 * (km / h);\n\nconstexpr auto kmph = km / h;\nquantity q3 = 60 * kmph;\n\nquantity q4 = 50 * (1 / s);\n

    With the new version, we removed this restriction, and now we can type:

    quantity q5 = 60 * km / h;\nquantity q6 = 50 / s;\n

    As a side effect, we introduced a breaking change . We can't use the following definition of hertz anymore:

    inline constexpr struct hertz : named_unit<\"Hz\", 1 / second, kind_of<isq::frequency>> {} hertz;\n

    and have to type either:

    inline constexpr struct hertz : named_unit<\"Hz\", one / second, kind_of<isq::frequency>> {} hertz;\n

    or

    inline constexpr struct hertz : named_unit<\"Hz\", inverse(second), kind_of<isq::frequency>> {} hertz;\n

    To be consistent, we applied the same change to the dimensions and quantity specifications definitions. Now, to define a frequency we have to type:

    C++23C++20Portable 
    inline constexpr struct frequency : quantity_spec<inverse(period_duration)> {} frequency;\n
    inline constexpr struct frequency : quantity_spec<frequency, inverse(period_duration)> {} frequency;\n
    QUANTITY_SPEC(frequency, inverse(period_duration));\n
    "},{"location":"blog/2023/12/09/mp-units-210-released/#make_xxx-factory-functions-replaced-with-two-parameter-constructors","title":"make_xxx factory functions replaced with two-parameter constructors","text":"

    In the initial version of the V2 framework, if someone did not like the multiply syntax to create a quantity we provided the make_quantity() factory function. A similar approach was used for quantity_point creation.

    This version removes those ( breaking change ) and introduces two parameter constructors:

    quantity q(42, si::metre);\nquantity_point qp(q, mean_sea_level);\n

    The above change encourages a better design and results in a terser code.

    "},{"location":"blog/2023/12/09/mp-units-210-released/#improved-definitions-of-becquerel-gray-and-sievert","title":"Improved definitions of becquerel, gray, and sievert","text":"

    In the initial V2 version, we lacked the definitions of the atomic and nuclear physics quantities, which resulted in simplified and unsafe definitions of becquerel, gray, and sievert units. We still do not model most of the quantities from this domain, but we've added the ones that are necessary for the definition of those units.

    Thanks to the above, the following expressions will not compile:

    quantity q1 = 1 * Hz + 1 * Bq;\nquantity<si::sievert> q2 = 42 * Gy;\n
    "},{"location":"blog/2023/12/09/mp-units-210-released/#compatibility-with-other-libraries-redesigned","title":"Compatibility with other libraries redesigned","text":"

    Another significant improvement in this version was redesigning the way we provide compatibility with other similar libraries. The interfaces of quantity_like_traits and quantity_point_like_traits were changed and extended to provide conversion not only from but also to entities from other libraries ( breaking change ).

    We've also introduced an innovative approach that allows us to specify if such conversions should happen implicitly or if they need to be forced explicitly.

    More on this subject can be found in the Interoperability with Other Libraries chapter.

    "},{"location":"blog/2023/12/09/mp-units-210-released/#point-origins-can-now-be-derived-from-each-other","title":"Point origins can now be derived from each other","text":"

    Previously, each class derived from absolute_point_origin was considered a unique independent point origin. On the other hand, it was OK to derive multiple classes from the same relative_point_origin, and those were specifying the same point in the domain. We found this confusing and limiting. This is why, in this version, the absolute_point_origin uses a CRTP idiom to be able to detect between points that should be considered different from the ones that should be equivalent.

    If we derive from the same instantiation of absolute_point_origin we end up with an equivalent point origin. This change allows us to provide different names for the same temperature points:

    inline constexpr struct absolute_zero : absolute_point_origin<absolute_zero, isq::thermodynamic_temperature> {} absolute_zero;\ninline constexpr struct zeroth_kelvin : decltype(absolute_zero) {} zeroth_kelvin;\n\ninline constexpr struct ice_point : relative_point_origin<absolute_zero + 273.15 * kelvin> {} ice_point;\ninline constexpr struct zeroth_degree_Celsius : decltype(ice_point) {} zeroth_degree_Celsius;\n

    Please note that this is a breaking change as well.

    "},{"location":"blog/2023/12/09/mp-units-210-released/#unit-symbol-text-can-now-be-properly-used-at-runtime","title":"Unit symbol text can now be properly used at runtime","text":"

    The interface of the previous definition of unit_symbol function allowed the use of the returned buffer only at compile-time. This was too limiting as users often want to use unit symbols at runtime (e.g., print them to the console). The new version redesigned the interface of this function ( breaking change ) to return a buffer that can be properly used at both compilation and runtime:

    std::string_view unit1 = unit_symbol(m / s);\nstd::cout << unit1 << \"\\n\";     // m/s\nstd::string_view unit2 = unit_symbol<{.solidus = unit_symbol_solidus::never}>(m / s);\nstd::cout << unit2 << \"\\n\";     // m s\u207b\u00b9\n
    "},{"location":"blog/2024/06/14/mp-units-220-released/","title":"mp-units 2.2.0 released!","text":"

    A new product version can be obtained from GitHub and Conan.

    Among other features, this release provides long-awaited support for C++20 modules, redesigns and enhances text output formatting, and greatly simplifies quantity point usage. This post describes those and a few other smaller interesting improvements, while a much longer list of the most significant changes introduced by the new version can be found in our Release Notes.

    "},{"location":"blog/2024/06/14/mp-units-220-released/#c20-modules-and-project-structure-cleanup","title":"C++20 modules and project structure cleanup","text":"

    GitHub Issue #7 was our oldest open issue before this release. Not anymore. After 4.5 years, we finally closed it, even though the C++ modules' support is still really limited.

    Info

    To benefit from C++ modules, we need at least:

    In the upcoming months, hopefully, the situation will improve with the bug fixes in CMake, gcc-14, and MSVC.

    Note

    More requirements for C++ modules support can be found in the CMake's documentation.

    To enable the compilation and distribution of C++ modules, a cxx_modules Conan or MP_UNITS_BUILD_CXX_MODULES CMake option has to be enabled.

    With the above, the following C++ modules will be provided:

    flowchart TD\n    mp_units --- mp_units.systems --- mp_units.core
    C++ Module CMake Target Contents mp_units.core mp-units::core Core library framework and systems-independent utilities mp_units.systems mp-units::systems All the systems of quantities and units mp_units mp-units::mp-units Core + Systems

    The easiest way to use them is just to import mp_units; at the beginning of your translation unit (see the Quick Start chapter for some usage examples).

    Note

    C++20 modules support still have some issues when imported from the installed CMake target. See the following GitLab issue for more details.

    In this release, we also highly limited the number of CMake targets ( breaking change ). Now, they correspond exactly to the C++ modules they provide. This means that many smaller partial targets were removed. We also merged text output targets with the core library's definition.

    The table below specifies where we can now find the contents of previously available CMake targets:

    Before Now mp-units::utility mp-units::core mp-units::core-io mp-units::core mp-units::core-fmt mp-units::core mp-units::{system_name} mp-units::systems

    While we were enabling C++ modules, we also had to refactor our header files slightly ( breaking change ). Some had to be split into smaller pieces (e.g., math.h), while others had to be moved to a different subdirectory (e.g., chrono.h).

    In version 2.2, the following headers have a new location or contents:

    Header File C++ Module Contents mp-units/math.h mp_units.core System-independent functions only mp-units/systems/si/math.h mp_units.systems Trigonometric functions using si::radian mp-units/systems/angular/math.h mp_units.systems Trigonometric functions using angular::radian mp-units/systems/si/chrono.h mp_units.systems std::chrono compatibility traits

    Benefiting from this opportunity, we also cleaned up core and systems definitions ( breaking change ).

    Regarding the library's core, we removed core.h and exposed only one header framework.h that provides all of the library's framework so the user does not have to enumerate files like unit.h, quantity.h, and quantity_point.h anymore. Those headers are not gone, they were put to the mp-units/framework subheader. So they are still there if you really need them.

    Regarding the changes in systems definitions, we moved the wrapper header files with the entire system definition to the mp-units/systems subdirectory. Additionally, they now also include framework.h, so a system include is enough to use the library. Thanks to that our users don't have to write tedious code like the below anymore:

    NowBefore 
    #include <mp-units/systems/cgs.h>\n#include <mp-units/systems/international.h>\n#include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n\n// ...\n
    #include <mp-units/quantity_point.h>\n#include <mp-units/systems/cgs/cgs.h>\n#include <mp-units/systems/international/international.h>\n#include <mp-units/systems/isq/isq.h>\n#include <mp-units/systems/si/si.h>\n\n// ...\n

    Additionally, we merged all of the compatibility-related macros into one header file mp-units/compat_macros.h. This header file should be explicitly included before importing C++ modules if we want to benefit from the Wide Compatibility tools.

    "},{"location":"blog/2024/06/14/mp-units-220-released/#better-control-over-the-librarys-api","title":"Better control over the library's API","text":"

    With this release, nearly all of the Conan and CMake build options were refactored with the intent of providing better control over the library's API.

    Previously, the library used the latest available feature set supported by a specific compiler. For example, quantity_spec definitions would use CRTP on an older compiler or provide a simpler API on a newer one thanks to the C++23 this deduction feature. This could lead to surprising results where the same code written by the user would compile fine on one compiler but not the other.

    From this release, all API extensions have their corresponding configuration options in Conan and CMake. With this, a user has full control over the API exposed by the library. Those options expose three values:

    Additionally, some CMake options were renamed to better express the impact on our users ( breaking change ). For example, now CMake options include:

    "},{"location":"blog/2024/06/14/mp-units-220-released/#configurable-contracts-checking","title":"Configurable contracts checking","text":"

    Before this release, the library always depended on gsl-lite to perform runtime contract and asserts checking. In this release we introduced new options to control if contract checking should be based on gsl-lite, ms-gsl, or may be completely disabled.

    "},{"location":"blog/2024/06/14/mp-units-220-released/#freestanding-support","title":"Freestanding support","text":"

    From this release it is possible to configure the library in the freestanding mode. This limits the functionality and interface of the library to be compatible with the freestanding implementations.

    Info

    To learn more, please refer to the Build options chapter.

    "},{"location":"blog/2024/06/14/mp-units-220-released/#simplified-quantity-point-support","title":"Simplified quantity point support","text":"

    This release significantly simplifies the usage of quantity points and affine space abstractions in general.

    Previously, the user always had to define an explicit point origin even if the domain being modeled does not have such an explicit origin. Now, in such cases, we can benefit from the implicit point origins. For example:

    NowBefore 
    quantity_point price_usd{100 * USD};\n
    constexpr struct zero final : absolute_point_origin<currency> {} zero;\n\nquantity_point price_usd = zero + 100 * USD;\n

    As we can see above, the new design allows direct-initializing quantity_point class template from a quantity, but only if the former one is defined in terms of the implicit point origin. Otherwise, an explicit origin still always has to be provided during initialization.

    Also, we introduced the possibility of specifying a default point origin in the unit definition. With that, we could provide proper temperature scales without forcing the user to always use the origins explicitly. Also, a new member function, .quantity_from_zero(), was introduced that always returns the quantity from the unit's specific point origin or from the implicit point origin otherwise.

    NowBefore 
    quantity_point temp{20 * deg_C};\nstd::cout << \"Temperature: \" << temp << \" (\"\n          << temp.in(deg_F).quantity_from_zero() << \", \"\n          << temp.in(K).quantity_from_zero() << \")\\n\";\n
    quantity_point temp = si::zeroth_degree_Celsius + 20 * deg_C;\nstd::cout << \"Temperature: \" << temp << \" (\"\n          << temp.in(deg_F).quantity_from(usc::zeroth_degree_Fahrenheit) << \", \"\n          << temp.in(K).quantity_from(si::zeroth_kelvin) << \")\\n\";\n

    More information about the new design can be found in The Affine Space chapter.

    "},{"location":"blog/2024/06/14/mp-units-220-released/#unified-temperature-point-origins-names","title":"Unified temperature point origins names","text":"

    By omission, we had the following temperature point origins in the library:

    With this release, the last one was renamed to usc::zeroth_degree_Fahrenheit to be consistently named with its corresponding unit and with the si::zeroth_degree_Celsius ( breaking change ).

    "},{"location":"blog/2024/06/14/mp-units-220-released/#changes-to-units-definitions","title":"Changes to units definitions","text":"

    There were several known issues when units were deriving from each other (e.g., #512 and #537). We could either highly complicate the framework to allow these which could result in much longer compilation times or disallow inheriting from units at all. We chose the second option.

    With this release all of of the units must be marked as final. To enforce this we have changed the definition of the Unit<T> concept, which now requires type T to be final ( breaking change ).

    WG21 Study Group 16 (Unicode) raised concerns about potential ABI issues when different translation units are compiled with different ordinary literal encodings. Those issues were resolved with a change to units definitions ( breaking change ). It affects only units that specify both Unicode and ASCII symbols. The new design requires the Unicode symbol to be provided as a UTF-8 literal.

    This also means that the basic_symbol_text has fixed character types for both symbols. This is why it was renamed to symbol_text ( breaking change ).

    NowBefore 
    inline constexpr struct ohm final : named_unit<symbol_text{u8\"\u03a9\", \"ohm\"}, volt / ampere> {} ohm;\n
    inline constexpr struct ohm : named_unit<basic_symbol_text{\"\u03a9\", \"ohm\"}, volt / ampere> {} ohm;\n

    Note

    On C++20-compliant compilers it should be enough to type the following in the unit's definition:

    inline constexpr struct ohm final : named_unit<{u8\"\u03a9\", \"ohm\"}, volt / ampere> {} ohm;\n
    "},{"location":"blog/2024/06/14/mp-units-220-released/#changes-to-dimension-quantity-specification-and-point-origins-definitions","title":"Changes to dimension, quantity specification, and point origins definitions","text":"

    Similarly to units, now also all dimensions, quantity specifications, and point origins have to be marked final ( breaking change ).

    NowBefore 
    inline constexpr struct dim_length final : base_dimension<\"L\"> {} dim_length;\ninline constexpr struct length final : quantity_spec<dim_length> {} length;\n\ninline constexpr struct absolute_zero final : absolute_point_origin<isq::thermodynamic_temperature> {} absolute_zero;\ninline constexpr auto zeroth_kelvin  = absolute_zero;\ninline constexpr struct kelvin final : named_unit<\"K\", kind_of<isq::thermodynamic_temperature>, zeroth_kelvin> {} kelvin;\n\ninline constexpr struct ice_point final : relative_point_origin<quantity_point{273'150 * milli<kelvin>}> {} ice_point;\ninline constexpr auto zeroth_degree_Celsius = ice_point;\ninline constexpr struct degree_Celsius final : named_unit<symbol_text{u8\"\u2103\", \"`C\"}, kelvin, zeroth_degree_Celsius> {} degree_Celsius;\n
    inline constexpr struct dim_length : base_dimension<\"L\"> {} dim_length;\ninline constexpr struct length : quantity_spec<dim_length> {} length;\n\ninline constexpr struct absolute_zero : absolute_point_origin<absolute_zero, isq::thermodynamic_temperature> {} absolute_zero;\ninline constexpr struct zeroth_kelvin : decltype(absolute_zero) {} zeroth_kelvin;\ninline constexpr struct kelvin : named_unit<\"K\", kind_of<isq::thermodynamic_temperature>, zeroth_kelvin> {} kelvin;\n\ninline constexpr struct ice_point : relative_point_origin<quantity_point{273'150 * milli<kelvin>}> {} ice_point;\ninline constexpr struct zeroth_degree_Celsius : decltype(ice_point) {} zeroth_degree_Celsius;\ninline constexpr struct degree_Celsius : named_unit<symbol_text{u8\"\u2103\", \"`C\"}, kelvin, zeroth_degree_Celsius> {} degree_Celsius;\n

    Please also note, that the absolute_point_origin does not use CRTP idiom anymore ( breaking change ).

    "},{"location":"blog/2024/06/14/mp-units-220-released/#improved-text-output","title":"Improved text output","text":"

    With this release, we can print not only whole quantities but also just their units or dimensions. Also, we fixed the std::format support so users can now enjoy full C++20 compatibility and don't have to use fmtlib anymore.

    We have also changed the grammar for quantities formatting ( breaking change ). It introduces the composition of underlying formatters that finally allows us to properly format user-defined representation types (assuming they have std::format support). Additionally, thanks to a new %? token, we can provide a custom format string that will properly print quantity of any unit.

    Here is a small preview of what is now available:

    using namespace mp_units::si::unit_symbols;\nusing namespace mp_units::international::unit_symbols;\nquantity q = (90. * km / h).in(mph);\n\nstd::cout << \"Number: \" << q.numerical_value_in(mph) << \"\\n\";\nstd::cout << \"Unit: \" << q.unit << \"\\n\";\nstd::cout << \"Dimension: \" << q.dimension << \"\\n\";\nstd::println(\"{::N[.2f]}\", q);\nstd::println(\"{:.4f} in {} of {}\", q.numerical_value_in(mph), q.unit, q.dimension);\nstd::println(\"{:%N in %U of %D:N[.4f]}\", q);\n
    Number: 55.9234\nUnit: mi/h\nDimension: LT\u207b\u00b9\n55.92 mi/h\n55.9234 in mi/h of LT\u207b\u00b9\n55.9234 in mi/h of LT\u207b\u00b9\n

    More on this subject can be found in the updated Text Output chapter.

    "},{"location":"blog/2024/06/14/mp-units-220-released/#improved-casts","title":"Improved casts","text":"

    We added a new conversion function. value_cast<Unit, Representation> forces the conversion of both a unit and representation type in one step and always ensures that the best precision is provided.

    Also, we have finally added proper implementations of value_cast and quantity_cast for quantity points.

    "},{"location":"blog/2024/06/14/mp-units-220-released/#even-better-error-messages","title":"Even better error messages","text":"

    This release made a few small refactorings that, without changing the user-facing API, allowed us to improve the readability of the generated types that can be observed in the compilation errors.

    Example 1 (clang):

    NowBefore 
    error: no matching function for call to 'time_to_goal'\n   26 |   const quantity ttg = time_to_goal(half_marathon_distance, pace);\n      |                        ^~~~~~~~~~~~\nnote: candidate template ignored: constraints not satisfied [with distance:auto = quantity<kilo_<metre>{}, double>,\n                                                                  speed:auto = quantity<derived_unit<second, per<kilo_<metre>>>{}, double>]\n   13 | QuantityOf<isq::time> auto time_to_goal(QuantityOf<isq::length> auto distance,\n      |                            ^\nnote: because 'QuantityOf<quantity<derived_unit<si::second, per<si::kilo_<si::metre> > >{{{}}}>, isq::speed>' evaluated to false\n   14 |                                         QuantityOf<isq::speed> auto speed)\n      |                                         ^\nnote: because 'QuantitySpecOf<std::remove_const_t<decltype(quantity<derived_unit<second, per<kilo_<metre> > >{{{}}}, double>::quantity_spec)>, struct speed{{{}}}>' evaluated to false\n   61 | concept QuantityOf = Quantity<Q> && QuantitySpecOf<std::remove_const_t<decltype(Q::quantity_spec)>, QS>;\n      |                                     ^\nnote: because 'implicitly_convertible(kind_of_<derived_quantity_spec<isq::time, per<isq::length> > >{}, struct speed{{{}}})' evaluated to false\n  147 |   QuantitySpec<T> && QuantitySpec<decltype(QS)> && implicitly_convertible(T{}, QS) &&\n      |                                                                         ^\n1 error generated.\nCompiler returned: 1\n
    error: no matching function for call to 'time_to_goal'\n   26 |   const quantity ttg = time_to_goal(half_marathon_distance, pace);\n      |                        ^~~~~~~~~~~~\nnote: candidate template ignored: constraints not satisfied [with distance:auto = quantity<kilo_<metre{{}}>{}, double>,\n                                                                  speed:auto = quantity<derived_unit<second, per<kilo_<metre{{}}>>>{}, double>]\n   13 | QuantityOf<isq::time> auto time_to_goal(QuantityOf<isq::length> auto distance,\n      |                            ^\nnote: because 'QuantityOf<quantity<derived_unit<si::second, per<si::kilo_<si::metre{{}}> > >{{{}}}>, isq::speed>' evaluated to false\n   14 |                                         QuantityOf<isq::speed> auto speed)\n      |                                         ^\nnote: because 'QuantitySpecOf<std::remove_const_t<decltype(quantity<derived_unit<second, per<kilo_<metre{{}}> > >{{{}}}, double>::quantity_spec)>, struct speed{{{}}}>' evaluated to false\n   61 | concept QuantityOf = Quantity<Q> && QuantitySpecOf<std::remove_const_t<decltype(Q::quantity_spec)>, QS>;\n      |                                     ^\nnote: because 'implicitly_convertible(kind_of_<derived_quantity_spec<isq::time, per<isq::length> >{{}, {{}}}>{}, struct speed{{{}}})' evaluated to false\n  147 |   QuantitySpec<T> && QuantitySpec<decltype(QS)> && implicitly_convertible(T{}, QS) &&\n      |                                                                         ^\n1 error generated.\nCompiler returned: 1\n

    Example 2 (gcc):

    NowBefore 
    error: no matching function for call to 'Box::Box(quantity<reference<isq::height, si::metre>(), int>, quantity<reference<horizontal_length, si::metre>(), int>,\n                                                  quantity<reference<isq::width, si::metre>(), int>)'\n   27 | Box my_box(isq::height(1 * m), horizontal_length(2 * m), isq::width(3 * m));\n      |                                                                           ^\nnote: candidate: 'Box::Box(quantity<reference<horizontal_length, si::metre>()>, quantity<reference<isq::width, si::metre>()>,\n                                          quantity<reference<isq::height, si::metre>()>)'\n   19 |   Box(quantity<horizontal_length[m]> l, quantity<isq::width[m]> w, quantity<isq::height[m]> h):\n      |   ^~~\nnote:   no known conversion for argument 1 from 'quantity<reference<isq::height, si::metre>(),int>'\n        to 'quantity<reference<horizontal_length, si::metre>(),double>'\n   19 |   Box(quantity<horizontal_length[m]> l, quantity<isq::width[m]> w, quantity<isq::height[m]> h):\n      |       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^\n
    error: no matching function for call to 'Box::Box(quantity<reference<isq::height(), si::metre()>(), int>, quantity<reference<horizontal_length(), si::metre()>(), int>,\n                                                  quantity<reference<isq::width(), si::metre()>(), int>)'\n   27 | Box my_box(isq::height(1 * m), horizontal_length(2 * m), isq::width(3 * m));\n      |                                                                           ^\nnote: candidate: 'Box::Box(quantity<reference<horizontal_length(), si::metre()>()>, quantity<reference<isq::width(), si::metre()>()>,\n                                          quantity<reference<isq::height(), si::metre()>()>)'\n   19 |   Box(quantity<horizontal_length[m]> l, quantity<isq::width[m]> w, quantity<isq::height[m]> h):\n      |   ^~~\nnote:   no known conversion for argument 1 from 'quantity<reference<isq::height(), si::metre()>(),int>'\n        to 'quantity<reference<horizontal_length(), si::metre()>(),double>'\n   19 |   Box(quantity<horizontal_length[m]> l, quantity<isq::width[m]> w, quantity<isq::height[m]> h):\n      |       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^\n
    "},{"location":"blog/2024/06/14/mp-units-220-released/#mathh-header-changes","title":"math.h header changes","text":"

    This release provided lots of changes to the mp_units/math.h header file.

    First, we got several outstanding contributions:

    Thanks!

    Additionally, we changed the namespace for trigonometric functions using SI units. Now they are inside of the mp_units::si subnamespace and not in mp_units::isq like it was the case before ( breaking change ).

    Also, the header itself was split into smaller pieces that improve C++20 modules definitions.

    "},{"location":"blog/2024/06/14/mp-units-220-released/#ratio-made-an-implementation-detail-of-the-library","title":"ratio made an implementation detail of the library","text":"

    We decided not to expose ratio and associated interfaces in the public part of the library ( breaking change ). Standardization of it could be problematic as we have std::ratio already.

    Alternatively, as in the public interface it was always only used with mag, we introduced a new helper called mag_ratio to provide the magnitude of the unit defined in terms of a rational conversion factor. Here is a comparison of the code with previous and current definitions:

    NowBefore 
    inline constexpr struct yard final : named_unit<\"yd\", mag_ratio<9'144, 10'000> * si::metre> {} yard;\ninline constexpr struct foot final : named_unit<\"ft\", mag_ratio<1, 3> * yard> {} foot;\n
    inline constexpr struct yard : named_unit<\"yd\", mag<ratio{9'144, 10'000}> * si::metre> {} yard;\ninline constexpr struct foot : named_unit<\"ft\", mag<ratio{1, 3}> * yard> {} foot;\n
    "},{"location":"blog/2024/09/27/mp-units-230-released/","title":"mp-units 2.3.0 released!","text":"

    A new product version can be obtained from GitHub and Conan.

    This release fine-tunes many key features of the library. This post describes the most interesting improvements, while a much longer list of the changes introduced by the new version can be found in our Release Notes.

    "},{"location":"blog/2024/09/27/mp-units-230-released/#cmake-and-conan-options-changed","title":"CMake and Conan options changed","text":"

    During the review on the ConanCenter, we got feedback that we should improve the handling of options for which value is automatically determined based on the current configuration. Instead of explicitly setting the auto value, we defer the choice between True/False until the configuration stage and set it there once all the settings are known. auto value for such option was removed ( breaking change ).

    If you didn't set any value at the command line for such options, everything stays the same for you. However, some changes are needed if you explicitly used auto like below:

    conan install . -o 'mp-units:std_format=auto' -s compiler.cppstd=23 -b missing\n

    Now you have to either skip such an option to keep automatic deduction:

    conan install . -s compiler.cppstd=23 -b missing\n

    or set it explicitly to True or False to force a specific configuration:

    conan install . -o 'mp-units:std_format=True' -s compiler.cppstd=23 -b missing\n
    "},{"location":"blog/2024/09/27/mp-units-230-released/#msvc-compiler-support","title":"MSVC compiler support","text":"

    The MSVC compiler has the most bugs in the C++20 support from all our compilers. However, with this release, we could apply many workarounds to the library's code to make it work. \ud83c\udf89

    Please note those workarounds were only applied to the library's code and not to our unit tests and examples. Trying to build the entire project on MSVC will inevitably fail to compile unless the MSVC bugs are resolved. MSVC developers still have some work to do.

    "},{"location":"blog/2024/09/27/mp-units-230-released/#representation-type-template-parameter-added-to-value-conversion-functions","title":"Representation type template parameter added to value conversion functions","text":"

    Previously, changing a representation type was only possible with a value_cast<NewRep>(q) non-member function while a change of unit was supported by all value_cast<NewU>(q), q.in(NewU), and q.force_in(NewU). The rationale for it was that passing an explicit type to a member function template requires a template disambiguator when we are dealing with a dependent name (e.g., quantity type is determined based on a template parameter).

    During a discussion in LEWGI at the St. Louis WG21 Meeting, we decided to provide such additional overloads despite possible issues when a dependent name is used. In such case, a user needs to provide a template disambiguator or switch back to using value_cast:

    // non-dependent name\nauto f(quantity<m, int> q)             { return q.in<double>(km); }\nauto g(quantity<m, int> q)             { return value_cast<double, km>(q); }\n\n// dependent name\nauto h(QuantityOf<isq::length> auto q) { return q.template in<double>(km); }\nauto i(QuantityOf<isq::length> auto q) { return value_cast<double, km>(q); }\n

    The table below provides all the value conversion functions in mp-units that may be run on x being the instance of either quantity or quantity_point:

    Forcing Representation Unit Member function Non-member function No Same u x.in(u) No T Same x.in<T>() No T u x.in<T>(u) Yes Same u x.force_in(u) value_cast<u>(x) Yes T Same x.force_in<T>() value_cast<T>(x) Yes T u x.force_in<T>(u) value_cast<u, T>(x) or value_cast<T, u>(x)"},{"location":"blog/2024/09/27/mp-units-230-released/#quantity-reference-specifiers","title":"Quantity reference specifiers","text":"

    The features described in this chapter directly solve an issue raised on std-proposals reflector. As it was reported, the code below may look correct, but it provides an invalid result:

    quantity Volume = 1.0 * m3;\nquantity Temperature = 28.0 * deg_C;\nquantity n_ = 0.04401 * kg / mol;\nquantity R_boltzman = 8.314 * N * m / (K * mol);\nquantity mass = 40.0 * kg;\nquantity Pressure = R_boltzman * Temperature.in(K) * mass / n_ / Volume;\nstd::cout << Pressure << \"\\n\";\n

    The problem is related to the accidental usage of a quantity rather than quantity_point for Temperature. This means that after conversion to kelvins, we will get 28 K instead of the expected 301.15 K, corrupting all further calculations.

    A correct code should use a quantity_point:

    quantity_point Temperature(28.0 * deg_C);\n

    This might be an obvious thing for domain experts, but new users of the library may not be aware of the affine space abstractions and how they influence temperature handling.

    After a lengthy discussion on handling such scenarios, we decided to:

    Here are the main points of this new design:

    1. All references/units that specify point origin in their definition (i.e., si::kelvin, \u00a0 \u00a0si::degree_Celsius, and usc::degree_Fahrenheit) are excluded from the multiply syntax ( breaking change ).

    2. A new delta quantity construction helper is introduced:

      • delta<m>(42) results with a quantity<si::metre, int>,
      • delta<deg_C>(5) results with a quantity<si::deg_C, int>.

    3. A new absolute quantity point construction helper is introduced:

      • absolute<m>(42) results with a quantity_point<si::metre, zeroth_point_origin<kind_of<isq::length>>{}, int>,
      • absolute<deg_C>(5) results with a quantity<si::metre, si::ice_point, int>.

    Info

    Please note that si::kelvin is also excluded from the multiply syntax to prevent the following surprising issues:

    NowBefore 
    quantity q = delta<K>(300);\nquantity_point qp = absolute<K>(300);\nstatic_assert(q.in(deg_C) != qp.in(deg_C).quantity_from_zero());\n
    quantity q(300 * K);\nquantity_point qp(300 * K);\nstatic_assert(q.in(deg_C) != qp.in(deg_C).quantity_from_zero());\n

    We believe that the code enforced with new utilities makes it much easier to understand what happens here.

    With such changes to the interface design, the offending code will not compile as initially written. Users will be forced to think more about what they write. To enable the compilation, the users have to create explicitly:

    Thanks to the new design, we can immediately see what happens here and why the result might be incorrect in the second case.

    "},{"location":"blog/2024/09/27/mp-units-230-released/#quantity_point_like_traits-are-based-on-numerical-value-instead-of-a-quantity","title":"quantity_point_like_traits are based on numerical value instead of a quantity","text":"

    In this release, we decided to fine-tune the traits that customize the conversion between custom quantity point types and the ones provided with mp-units ( breaking change ).

    Previously, such type traits were based on the quantity type. This was inconsistent with quantity_like_traits, that is working on raw values. Also, there are cases where a custom quantity point abstraction is not modelled with a quantity type. In such cases, the previous approach required additional types to be introduced for no good reason.

    NowBefore 
    template<>\nstruct mp_units::quantity_point_like_traits<Timestamp> {\n  static constexpr auto reference = si::second;\n  static constexpr auto point_origin = default_point_origin(reference);\n  using rep = decltype(Timestamp::seconds);\n\n  static constexpr convert_implicitly<rep> to_numerical_value(Timestamp ts)\n  {\n    return ts.seconds;\n  }\n\n  static constexpr convert_explicitly<Timestamp> from_numerical_value(rep v)\n  {\n    return Timestamp(v);\n  }\n};\n
    template<>\nstruct mp_units::quantity_point_like_traits<Timestamp> {\n  static constexpr auto reference = si::second;\n  static constexpr auto point_origin = default_point_origin(reference);\n  using rep = decltype(Timestamp::seconds);\n\n  static constexpr convert_implicitly<quantity<reference, rep>> to_quantity(Timestamp ts)\n  {\n    return ts.seconds * si::second;\n  }\n\n  static constexpr convert_explicitly<Timestamp> from_quantity(quantity<reference, rep> q)\n  {\n    return Timestamp(q.numerical_value_ref_in(si::second));\n  }\n};\n

    Note

    The old behavior is deprecated and will be removed in future releases.

    "},{"location":"blog/2024/09/27/mp-units-230-released/#magpi","title":"mag<pi>","text":"

    With this release, we introduced a new strongly-typed constant to create a magnitude involving scaling by pi. The solution used before was not consistent with magnitudes of integral values and also was leaking a floating-point value of std::numbers::pi_v<long double> to the resulting magnitude type. With the new approach, this is no longer the case, and the user-facing interface is more consistent:

    NowBefore 
    inline constexpr struct degree final : named_unit<{u8\"\u00b0\", \"deg\"}, mag<pi> / mag<180> * si::radian> {} degree;\n
    inline constexpr struct degree final : named_unit<{u8\"\u00b0\", \"deg\"}, mag_pi / mag<180> * si::radian> {} degree;\n

    Note

    The old mag_pi helper is marked as deprecated and will be removed in future releases.

    "},{"location":"blog/2024/09/27/mp-units-230-released/#common-units","title":"Common units","text":"

    Adding or subtracting two quantities of different units will force the library to find a common unit for those. This is to prevent data truncation. For the cases when one of the units is an integral multiple of the another, the resulting quantity will use a \"smaller\" one in its result. For example:

    static_assert((1 * kg + 1 * g).unit == g);\nstatic_assert((1 * km + 1 * mm).unit == mm);\nstatic_assert((1 * yd + 1 * mi).unit == yd);\n

    However, in many cases an arithmetic on quantities of different units will result in a yet another unit. This happens when none of the source units is an integral multiple of another. In such cases, the library returns a special type that denotes that we are dealing with a common unit of such an equation.

    Previously we returned a scaled unit calculated against our arbitrarily appointed reference unit. This resulted often in a long and messy type exposing the prime-factorized magnitude of the unit (implementation detail). In this release, we introduced a new common_unit wrapper for such cases:

    NowBefore 
    quantity q = 1 * km + 1 * mi;  // quantity<common_unit<international::mile, si::kilo_<si::metre>>{}, int>\n
    quantity q = 1 * km + 1 * mi;  // quantity<scaled_unit<magnitude<power_v<2, 3>{}, power_v<5, -3>{}>{}, si::metre>{}, int>\n

    Note

    A user should never explicitly instantiate a common_unit class template. The library's framework will do it based on the provided quantity equation.

    Such units need special printing rules for their symbols. As they represent a minimum set of common units resulting from the addition or subtraction of multiple quantities, from this release, we print all of them as a scaled version of the source unit. Previously we were printing them relative to some arbitrary reference unit (implementation detail) that often was not spelled by the user at all in the source code. For example the following:

    std::cout << 1 * km + 1 * mi << \"\\n\";\nstd::cout << 1 * nmi + 1 * mi << \"\\n\";\nstd::cout << 1 * km / h + 1 * m / s << \"\\n\";\n

    will print:

    NowBefore 
    40771 ([1/25146] mi = [1/15625] km)\n108167 ([1/50292] mi = [1/57875] nmi)\n23 ([1/5] km/h = [1/18] m/s)\n
    40771 [8/125] m\n108167 [4/125] m\n23 [1/18] m/s\n

    Thanks to the above, it might be easier for the user to reason about the magnitude of the resulting unit and its impact on the value stored in the quantity.

    Info

    In order to provide common_unit strong type unit wrapper we had to rename all the common_XXX() functions to get_common_XXX() ( breaking change ).

    "},{"location":"blog/2024/09/27/mp-units-230-released/#superpowers-of-the-unit-one","title":"Superpowers of the unit one","text":"

    In this release, we also added a long-awaited change. From now on a quantity of a unit one can be:

    NowBefore 
    quantity<one> inc(quantity<one> q) { return q + 1; }\nvoid legacy(double) { /* ... */ }\n\nif (auto q = inc(42); q != 0)\n  legacy(static_cast<int>(q));\n
    quantity<one> inc(quantity<one> q) { return q + 1 * one; }\nvoid legacy(double) { /* ... */ }\n\nif (auto q = inc(42 * one); q != 0 * one)\n  legacy(q.numerical_value_in(one));\n

    This property also expands to usual arithmetic operators.

    With the above change, we can now achieve the same results in a terser way:

    NowBefore 
    static_assert(10 * km / (5 * km) == 2);\nconst quantity gain = 1. / index;\n
    static_assert(10 * km / (5 * km) == 2 * one);\nconst quantity gain = 1. / index * one;\n

    Note

    Those rules do not apply to all the dimensionless quantities. It would be unsafe and misleading to allow such operations on units with a magnitude different than 1 (e.g., percent or radian).

    "},{"location":"blog/2024/09/27/mp-units-230-released/#import-std-support","title":"import std; support","text":"

    This release brings experimental support for import std;. The only compiler that supports it for now is clang-18+. Until all the compilers start to support it and CMake removes the experimental tag from this feature, we will also keep it experimental.

    As all of the C++ compilers are buggy for now, it is not allowed to bring the same definitions through the import std; and regular header files. This applies not only to the current project but also to all its dependencies. This is why, in order to use it with mp-units, we need to disable all the dependencies as well (enforced with conanfile.py). It means that we have to use std::format (instead of fmtlib) and remove functions contract checking.

    With the above assumptions, we can refactor our smoot example to:

    import mp_units;\nimport std;\n\nusing namespace mp_units;\n\ninline constexpr struct smoot final : named_unit<\"smoot\", mag<67> * usc::inch> {} smoot;\n\nint main()\n{\n  constexpr quantity dist = 364.4 * smoot;\n  std::println(\"Harvard Bridge length = {::N[.1f]} ({::N[.1f]}, {::N[.2f]}) \u00b1 1 \u03b5ar\",\n               dist, dist.in(usc::foot), dist.in(si::metre));\n}\n
    "},{"location":"blog/2024/09/27/mp-units-230-released/#unit_can_be_prefixed-removed","title":"unit_can_be_prefixed removed","text":"

    Previously, the unit_can_be_prefixed type trait was used to limit the possibility to prefix some units that are officially known as non-prefixable (e.g., hour, minute).

    It turned out that it is not easy to determine whether some units can be prefixed. For example, for degree Celsius, the ISO 80000-5 standard explicitly states:

    Prefixes are not allowed in combination with the unit \u00b0C.

    On the other hand this NIST page says:

    Prefix symbols may be used with the unit symbol \u00baC and prefix names may be used with the unit name \u201cdegree Celsius.\u201d For example, 12 m\u00baC (12 millidegrees Celsius) is acceptable.

    It seems that it is also a common engineering practice.

    To prevent such issues, we decided to simplify the library's design and remove the unit_can_be_prefixed type trait ( breaking change ).

    From now on, every named unit in the library can be prefixed with the SI or IEC prefix.

    "},{"location":"blog/2024/09/27/mp-units-230-released/#iec80000-system-renamed-to-iec","title":"iec80000 system renamed to iec","text":"

    As we mentioned IEC already, in this release, we decided to rename the name of the system and its corresponding namespace from iec80000 to iec ( breaking change ). This involves renaming of a defining header file and of the namespace it provides.

    With this change it should be easier to type the namespace name. This name is also more correct for some quantities and units that are introduced by IEC but not necessarily in the ISO/IEC 80000 series of documents (e.g., iec::var).

    Note

    The old iec80000 namespace in iec8000.h is marked as deprecated and will be removed in future releases.

    "},{"location":"blog/2024/09/27/mp-units-230-released/#error-messages-related-improvements","title":"Error messages-related improvements","text":"

    The readability of compile-time error messages is always a challenge for generic C++ libraries. However, for quantities and units library, generating readable errors is the most important requirement. If you do not make errors, you do not need such a library in your project .

    This is why we put lots of effort into improving here. Besides submitting compiler bugs to improve on their part, we also try to do our best here.

    Some compilers do not present the type resulting from calling a function within a template argument. This ends up with statements like get_quantity_spec(si::second{}) in the error message. Some less experienced users of the library may not know what this mean, and then why the conversion error happens.

    To improve this, we injected additional helper concepts into the definitions. It results with a bit longer but a more readable error in the end.

    For example:

    NowBefore 
    error: no matching member function for call to 'in'\n   15 | const quantity time_to_goal = (distance * speed).in(s);\n      |                               ~~~~~~~~~~~~~~~~~~~^~\nnote: candidate template ignored: constraints not satisfied [with ToU = struct second]\n  221 |   [[nodiscard]] constexpr QuantityOf<quantity_spec> auto in(ToU) const\n      |                                                          ^\nnote: because 'detail::UnitCompatibleWith<si::second, unit, quantity_spec>' evaluated to false\n  219 |   template<detail::UnitCompatibleWith<unit, quantity_spec> ToU>\n      |            ^\nnote: because '!AssociatedUnit<si::second>' evaluated to false\n  164 |   (!AssociatedUnit<U> || UnitOf<U, QS>) && detail::UnitConvertibleTo<FromU, U{}>;\n      |    ^\nnote: and 'UnitOf<si::second, kind_of_<derived_quantity_spec<power<isq::length, 2>, per<isq::time> > >{}>' evaluated to false\n  164 |   (!AssociatedUnit<U> || UnitOf<U, QS>) && detail::UnitConvertibleTo<FromU, U{}>;\n      |                          ^\nnote: because 'detail::QuantitySpecConvertibleTo<get_quantity_spec(si::second{}), kind_of_<derived_quantity_spec<power<isq::length, 2>, per<isq::time> > >{}>' evaluated to false\n  141 |                  detail::QuantitySpecConvertibleTo<get_quantity_spec(U{}), QS> &&\n      |                  ^\nnote: because 'implicitly_convertible(kind_of_<struct time>{}, kind_of_<derived_quantity_spec<power<isq::length, 2>, per<isq::time> > >{})' evaluated to false\n  151 |   implicitly_convertible(From, To);\n      |   ^\n1 error generated.\nCompiler returned: 1\n
    error: no matching member function for call to 'in'\n   15 | const quantity time_to_goal = (distance * speed).in(s);\n      |                               ~~~~~~~~~~~~~~~~~~~^~\nnote: candidate template ignored: constraints not satisfied [with U = struct second]\n  185 |   [[nodiscard]] constexpr QuantityOf<quantity_spec> auto in(U) const\n      |                                                          ^\nnote: because 'detail::UnitCompatibleWith<si::second, unit, quantity_spec>' evaluated to false\n  183 |   template<detail::UnitCompatibleWith<unit, quantity_spec> U>\n      |            ^\nnote: because '!AssociatedUnit<si::second>' evaluated to false\n  207 |   (!AssociatedUnit<U> || UnitOf<U, QS>)&&(detail::have_same_canonical_reference_unit(U{}, U2));\n      |    ^\nnote: and 'UnitOf<si::second, kind_of_<derived_quantity_spec<power<isq::length, 2>, per<isq::time> > >{}>' evaluated to false\n  207 |   (!AssociatedUnit<U> || UnitOf<U, QS>)&&(detail::have_same_canonical_reference_unit(U{}, U2));\n      |                          ^\nnote: because 'implicitly_convertible(get_quantity_spec(si::second{}), kind_of_<derived_quantity_spec<power<length, 2>, per<time> > >{})' evaluated to false\n  187 |   implicitly_convertible(get_quantity_spec(U{}), QS) &&\n      |   ^\n1 error generated.\nCompiler returned: 1\n

    Note

    The above error messages were stripped a bit of the additional information (file name, namespace name, nested curlies) to provide better readability.

    "},{"location":"blog/2024/11/05/mp-units-240-released/","title":"mp-units 2.4.0 released!","text":"

    A new product version can be obtained from GitHub and Conan.

    This release was unexpected. We planned a significant new feature to happen next, but while preparing for it, and also while writing API Reference documentation, we made so many vital fixes and improvements that we decided that they deserve a dedicated release first.

    This post describes the most significant improvements while a much longer list of the changes introduced by the new version can be found in our Release Notes.

    "},{"location":"blog/2024/11/05/mp-units-240-released/#isq-quantities-cleanup","title":"ISQ quantities cleanup","text":"

    Initially, we kept quantities defined in \"IEC 80000-13: Information science and technology\" in a standalone iec80000 namespace, which was renamed to iec in the previous release. It turned out that this was incorrect. Those quantities are also a part of the ISQ. This is why, in this release, we moved all of them to the isq namespace ( breaking change ).

    From now on, iec namespace does not provide any quantities and serves purely as a system of units definition. It contains binary prefixes (based on the powers of two) and some units introduced by IEC (e.g., var, erlang, bit, or `baud).

    Note

    The quantities in iec namespace are now deprecated and will be removed in future releases.

    Also, it turns out that the latest ISO 80000-3 revision makes a small cleanup to the phase_speed and group_speed quantities. Those were always defined as scalar quantities but also had alternative names phase_velocity and group_velocity. This is misleading as velocity is typically considered a vector quantity. It is why those XXX_velocity aliases were removed from the ISO standard and from mp-units library ( breaking change ).

    "},{"location":"blog/2024/11/05/mp-units-240-released/#units-equality","title":"Units equality","text":"

    Previously we assumed that units like J, N m, and kg m\u00b2/s\u00b2 are equal. In some cases, this might not be entirely correct. Some quantities require a specific derived unit instead of a unit with a special name. For example:

    This is why, starting from this release units like J, N m, and kg m\u00b2/s\u00b2 will not compare equal ( breaking change ). However, they are deemed equivalent:

    static_assert(equivalent(J, N * m));\nstatic_assert(equivalent(W, V * A));\n
    "},{"location":"blog/2024/11/05/mp-units-240-released/#portable-text-output","title":"Portable text output","text":"

    From the very beginning, the text output of symbols could be formatted in two different ways:

    mp-units used the terms \"Unicode\" or \"ASCII\" and 'U' or 'A' formatting options for them. Even though those terms are widely understood in the C++ community, they are technically incorrect.

    During the recent SG16 meeting, we looked for proper alternatives and ended up with the \"portable\" and \"UTF-8\" terms ( breaking change ).

    From now on, we will provide the following:

    Note

    The old identifiers and formatting options are now deprecated and will be removed in future releases.

    "},{"location":"blog/2024/11/05/mp-units-240-released/#char_traits-removed-from-fixed_string","title":"char_traits removed from fixed_string","text":"

    During the same SG16 meeting, the room was strongly against providing char_traits for fixed_string. This is why char_traits support was removed in this release ( breaking change ).

    "},{"location":"blog/2024/11/05/mp-units-240-released/#improved-units-text-output","title":"Improved units' text output","text":"

    In the previous release, we introduced common unit abstraction. Initially, all its components were printed in parenthesis which contained a list of all the scaled units separated with =. After some feedback, we decided to change it to a new syntax.

    For example, the following:

    std::cout << 1 * km + 1 * mi << \"\\n\";\nstd::cout << 1 * nmi + 1 * mi << \"\\n\";\nstd::cout << 1 * km / h + 1 * m / s << \"\\n\";\n

    will print:

    NowBefore 
    40771 EQUIV{[1/25146 mi], [1/15625 km]}\n108167 EQUIV{[1/50292 mi], [1/57875 nmi]}\n23 EQUIV{[1/5 km/h], [1/18 m/s]}\n
    40771 ([1/25146] mi = [1/15625] km)\n108167 ([1/50292] mi = [1/57875] nmi)\n23 ([1/5] km/h = [1/18] m/s)\n

    As we can see above, the scaled units output changed as well. Now, the entire scaled unit is encapsulated within [...] brackets to better denote its scope.

    Additionally, small magnitudes of scaled units do not use the power of 10, and also scaled units do not have a composition priority over the derived units anymore.

    As a result of those changes, the following:

    constexpr Unit auto L_per_100km = L / (mag<100> * km);\nstd::cout << 6.7 * L_per_100km << \"\\n\";\n

    prints:

    NowBefore 
    6.7 L/[100 km]\n
    6.7 \u00d7 10\u207b\u00b2 l/km\n

    One more change that we can see above is that litre now use 'L' instead of 'l' for its symbol. The latter one too often is confused with the number 1.

    The next improvement adds proper formatting support for magnitudes. All of the formatting options that were working before for the unit symbols now also work for magnitudes.

    For example:

    using enum text_encoding;\nusing enum unit_symbol_solidus;\nusing usf = unit_symbol_formatting;\n\nstatic_assert(unit_symbol(mag<1> / (mag<2> * mag<pi>)*metre) == \"[2\u207b\u00b9 \ud835\udf0b\u207b\u00b9 m]\");\nstatic_assert(unit_symbol<usf{.solidus = always}>(mag<1> / (mag<2> * mag<pi>)*metre) == \"[1/(2 \ud835\udf0b) m]\");\nstatic_assert(unit_symbol<usf{.encoding = portable, .solidus = always}>(mag<1> / (mag<2> * mag<pi>)*metre) ==\n              \"[1/(2 pi) m]\");\n

    As we can see above, the library also learned how to print magnitude symbols. This required a change in the mag_constant definition. Now, it takes a magnitude symbol and has to be final like for other similar types in the library ( breaking change ):

    inline constexpr struct pi final : mag_constant<symbol_text{u8\"\u03c0\", \"pi\"}, std::numbers::pi_v<long double>> {} pi;\ninline constexpr auto \u03c0 = pi;\n
    "},{"location":"blog/2024/11/05/mp-units-240-released/#unicode-identifiers","title":"Unicode identifiers","text":"

    The example above introduced something interesting: a \u03c0 identifier for a variable. With the latest changes to the C++ language, we can officially use Unicode symbols as identifiers in the C++ code.

    In this release, we've added Unicode identifiers support not only for \u03c0 magnitude constant but also for unit symbols.

    Now we can type the following:

    With UTF-8 glyphsPortable 
    quantity resistance = 60 * k\u03a9;\nquantity capacitance = 100 * \u00b5F;\n
    quantity resistance = 60 * kohm;\nquantity capacitance = 100 * uF;\n

    This might make the source code easier to understand, but typing those identifiers can be tricky. Sometimes, the best solution to type it might be a copy-paste approach. If we do not like this idea, we can still use old portable identifiers for those as well.

    "},{"location":"blog/2024/11/05/mp-units-240-released/#convertibility-with-quantitylike-and-quantitypointlike-entities","title":"Convertibility with QuantityLike and QuantityPointLike entities","text":"

    In this release, we decided to fine-tune further the traits that customize the conversion between custom quantity and quantity point types and the ones provided with mp-units ( breaking change ).

    Previously, to_numerical_value and from_numerical_value returned a type wrapped in a special tag type describing the conversion type (explicit or implicit).

    This was a novel and experimental approach. Finally, we decided not to do it and used a bit more verbose but a more standard solution. From now on, we need to provide two additional static data members of type bool:

    NowBefore 
    template<>\nstruct mp_units::quantity_point_like_traits<Timestamp> {\n  static constexpr auto reference = si::second;\n  static constexpr auto point_origin = default_point_origin(reference);\n  static constexpr bool explicit_import = false;\n  static constexpr bool explicit_export = true;\n  using rep = decltype(Timestamp::seconds);\n\n  static constexpr rep to_numerical_value(Timestamp ts)\n  {\n    return ts.seconds;\n  }\n\n  static constexpr Timestamp from_numerical_value(rep v)\n  {\n    return Timestamp(v);\n  }\n};\n
    template<>\nstruct mp_units::quantity_point_like_traits<Timestamp> {\n  static constexpr auto reference = si::second;\n  static constexpr auto point_origin = default_point_origin(reference);\n  using rep = decltype(Timestamp::seconds);\n\n  static constexpr convert_implicitly<rep> to_numerical_value(Timestamp ts)\n  {\n    return ts.seconds;\n  }\n\n  static constexpr convert_explicitly<Timestamp> from_numerical_value(rep v)\n  {\n    return Timestamp(v);\n  }\n};\n
    "},{"location":"blog/2024/11/05/mp-units-240-released/#symbolic-constants-implementation-should-be-implementation-defined","title":"Symbolic constants implementation should be implementation-defined","text":"

    In the process of writing API Reference, we decided to hide all the metadata associated with symbolic constants - tag types used to define units, dimensions, quantity specification, etc. ( breaking change ).

    All the types and values exposed by such types are needed only in the implementation details of the library. Users should not need them. Hiding those and making them implementation-defined gives other vendors the freedom to choose different ways to implement features of this library in their codebases.

    Important

    Based on Hyrum's Law some users may depend on this information already, and this release will break their code.

    If that is the case for you, we would love to hear about your use case and its rationale. It may mean that we should either:

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/","title":"Bringing Quantity-Safety To The Next Level","text":"

    All quantities and units libraries need to be unit-safe. Most of the libraries on the market do this correctly. Some of them are also dimension-safe, which adds another level of protection for their users.

    mp-units is probably the only library on the market that additionally is quantity-safe. This gives a new quality and possibilities. I've described the major idea behind it, implementation details, and benefits to the users in the series of posts about the International System of Quantities.

    However, this is only the beginning. We've always planned more and worked on the extensions in our free time. In this post, I will describe:

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#quantity-characters","title":"Quantity characters","text":"

    A quantity character determines the properties and operations that can be performed on the numerical value of a quantity.

    Quantities defined by the ISQ may be of the following characters:

    From the beginning, mp-units V2 was meant to properly support quantities of various characters. By default, all quantity types are scalars, but we can set any other quantity character in a quantity_spec definition. For example:

    inline constexpr struct displacement final : quantity_spec<length, quantity_character::vector> {} displacement;\n

    Character of derived quantities is inherited from the quantity equation taking into account the operations and their ingredients. For example the below velocity quantity will automatically get a vector character without the need to explicitly state it in the definition:

    inline constexpr struct velocity final : quantity_spec<displacement / duration> {} velocity;\n

    Similarly, the below will yield a speed quantity of a scalar character:

    inline constexpr struct speed final : quantity_spec<magnitude(velocity)> {} speed;\n
    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#representation-types","title":"Representation types","text":"

    mp-units V2 requires providing representation types compatible with a specific character set in its quantity_spec definition:

    template<Reference auto R, RepresentationOf<get_quantity_spec(R)> Rep = double>\nclass quantity;\n

    For example, this allows us to check that vector representation type is used to construct a velocity quantity and to ensure that speed gets a scalar:

    quantity q = vector{1, 2, 3} * m / s;\nquantity velocity = isq::velocity(q);\n// quantity speed = isq::speed(q);     // Compile-time error\n

    Another example here may be a complex power quantity that should use a representation type modeling a complex number, but apparent power, active power, and reactive power should get scalars.

    As we can see above, in the case of q, we can use any representation type with a quantity kind that just specify a unit (simple quantities). However, we need to provide a compatible representation type when we want to use strongly-typed quantities and be quantity-safe.

    Such checks already prevent many simple but common errors of mixing similar quantities in a specific domain.

    Info

    It is a common engineering practice to use fundamental types for vector quantities when we know the direction of the vector. For example, in many cases, we use double to express velocity or acceleration. In such cases, negative values mean moving backward or decelerating. This is why we also decided to allow such use cases in the library. A scalar representation type that provides abs() member or non-member function or works with std::abs() is considered a one-dimensional vector type:

    quantity speed = isq::speed(60 * km / h);\nquantity velocity = isq::velocity(60 * km / h);\n
    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#character-specific-operations","title":"Character-specific operations","text":"

    Checking the representation type is only the first step in bringing additional safety. The real power comes with implementing character-specific operations.

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#current-state-of-the-art","title":"Current state of the art","text":"

    Most units libraries on the market (not only for C++) provide only regular arithmetic operations for scalars and don't constrain them for quantities of other characters. They also do not offer any character-specific operations.

    For example, let's look closer into vector quantities. Most of the libraries on the market will happily accept the following or similar code:

    auto force = get_force();\nauto length = get_length();\nauto work = force * length;\n

    They will also accept the following line:

    auto moment_of_force = force * length;\n

    Does it mean that moment of force and work are the same quantities? Of course not! It is just how naive most libraries are today.

    But first, to defend them, I must admit that the behavior above is partially OK. force * length could yield some specific quantity, but it is definitely not work or moment of force.

    There are two problems here:

    1. Libraries on the market are not aware of the characters of the quantities being used in the equation. This means they can't prevent scalar arithmetic operations from being performed on vector quantities. This typically leads to compile-time errors when a proper linear algebra representation type is used in a quantity, as most linear algebra libraries will not overload operator* for vectors, and those that do, treat it as a dot product, which returns a scalar.
    2. None of the libraries allows us to constrain the return type of such multiplication with a specific quantity type to specify exactly what we want to achieve. Most of them allow for replacing auto with a type that describes just a unit, or, at best, the dimension. This means that all of them are unit-safe, and some are also dimension-safe. However, this is not helpful here and does not allow the library to do any additional compile-time checks on the resulting quantities. The fact that we named the results as work or moment_of_force does not mean anything to the compiler or the library being used.

    This isn't good.

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#benefits-of-quantity-safe-library","title":"Benefits of quantity-safe library","text":"

    As we've stated in the beginning, mp-units, besides being unit-safe and dimension-safe, is also quantity-safe. Let's see what it means.

    Note

    The features described below are planned for the next major release of the library and are not available on the master branch as of today.

    First, we repeat what other libraries did:

    quantity force = get_force();\nquantity length = get_length();\nquantity q1 = force * length;\n

    The code compiles as long as length is a scalar quantity with a scalar representation type. We can always multiply or divide a vector quantity (e.g., force) by a scalar one.

    However, things stop compiling when we want to convert the obtained result to a specific quantity type:

    // quantity moment_of_force = isq::moment_of_force(q1);  // Compile-time error\n// quantity work = isq::work(q1);                        // Compile-time error\n

    Neither moment of force nor work quantity can be created from a scalar length. We need very specific vector quantities of kind length to do that:

    quantity displacement = get_displacement();\nquantity position_vector = get_position_vector();\n

    Now, if we try to multiply the variables as before, we will end up with a compilation error:

    // quantity q2 = force * displacement;                   // Compile-time error\n// quantity q3 = force * position_vector;                // Compile-time error\n

    Multiplication on vectors is mathematically not defined. We have to use proper operations:

    quantity q2 = scalar_product(force, displacement);\nquantity q3 = scalar_product(force, position_vector);\nquantity q4 = vector_product(force, displacement);\nquantity q5 = vector_product(force, position_vector);\n

    All of the above compile and result in some quantities. After that, we can try to convert those results to our required quantities:

    quantity work = isq::work(q2).in[J];\n// quantity work = isq::work(q3);                        // Compile-time error\n// quantity work = isq::work(q4);                        // Compile-time error\n// quantity work = isq::work(q5);                        // Compile-time error\n

    Important

    It is essential to realize that just like multiplication and division are for scalars, vector and scalar products are for vectors. We never want to accept a quantity that accidentally was created with multiplication instead of division of its arguments or with the scalar product instead of a vector product, right?

    So we are done with work. Let's create a moment of force quantity as well. It might be surprising to many that none of the following code compiles:

    // quantity moment_of_force = isq::moment_of_force(q2);  // Compile-time error\n// quantity moment_of_force = isq::moment_of_force(q3);  // Compile-time error\n// quantity moment_of_force = isq::moment_of_force(q4);  // Compile-time error\n// quantity moment_of_force = isq::moment_of_force(q5);  // Compile-time error\n

    Do you know why it does not compile? Please try to think about it for a minute and figure out what is the problem before checking the answer below.

    !!! Spoiler alert !!!

    Vector product is anti-commutative. Similarly to the division for scalars, for a vector product it is important to decide which quantity we put on the left and right-hand side of the operation.

    To make it compile, we need to reverse the arguments of a vector_product() operation:

    quantity q6 = vector_product(position_vector, force);\nquantity moment_of_force = isq::moment_of_force(q6);\n

    Do you start to see the need for such checks at compile-time already?

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#explicit-conversions-are-not-really-needed","title":"Explicit conversions are not really needed","text":"

    You may be worried by the fact that we needed explicit quantity conversions above and that the code without them compiled fine. It might look like a safety pitfall, but it is really not an issue.

    The code above used a quantity CTAD placeholder which works a bit like auto. It accepts any quantity and deduced proper type for it. And all of the above operations resulted in some quantities, but often not the ones we were interested in.

    In the production code, we deal with strong types in many places (members in classes, function arguments and return types, etc.). In generic code, we should use concepts to constrain template parameters. This will be enough to guarantee quantity-safety.

    For example:

    void func1(quantity<isq::work[J]> w);\nvoid func2(QuantityOf<isq::moment_of_force> auto mof);\n\nfunc1(q2);\nfunc2(q6);\n// func1(q6);  // Compile-time error\n// func2(q2);  // Compile-time error\n
    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#peeking-under-the-hood","title":"Peeking under the hood","text":"

    Let's look at the definitions of work and moment of force quantities to understand how and why the above works:

    inline constexpr struct work final : quantity_spec<scalar_product(force, displacement)> {} work;\ninline constexpr struct moment_of_force final : quantity_spec<vector_product(position_vector, force)> {} moment_of_force;\n

    scalar_product() and vector_product() functions are overloaded not only for quantity but also for quantity_spec types. The results of such operations are symbolic expressions that identify those operations. When used as a quantity recipe in a quantity_spec definition, they tell the library which derived quantities may be implicitly converted to our quantity.

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#what-do-other-libraries-do","title":"What do other libraries do?","text":"

    I am probably not wrong in stating that none of the major C++ units libraries on the market provides vector or complex operations on quantities. This is why none of them will work when a proper representation type will be provided to a quantity. Trying to do any operations on a quantity with a linear algebra vector as its representation type will fail to compile.

    This is also mostly true for other programming languages. A great exception, and in fact the only library that I know which provides such operations, is Python's Pint (thanks to NumPy support).

    As other libraries do not support quantities of a vector type, they require users to create homogenous vectors of quantities and do all of the linear algebra operations with a 3rd party library. This approach can't be quantity-safe!

    In such scenarios, the units library can't detect if an external linear algebra library performs a scalar or vector product operation. It only observes the individual multiplications on scalar ingredients of an external vector type. This is actually why such multiplication operations are provided in other units libraries in the first place.

    Let's compare those approaches:

    Quantity-SafeAlso Quantity-SafeOther units libraries 
    quantity displacement_1 = isq::displacement(la::vector{1, 2, 3} * m);\nquantity displacement_2 = isq::displacement(la::vector{2, 1, 0} * m);\nquantity displacement = displacement_1 + displacement_2;\nquantity force = isq::force(la::vector{42, 42, 42} * N);\nquantity work = isq::work(scalar_product(force, displacement));\n
    quantity displacement_1 = la::vector{1, 2, 3} * m;\nquantity displacement_2 = la::vector{2, 1, 0} * m;\nquantity displacement = displacement_1 + displacement_2;\nquantity force = la::vector{42, 42, 42} * N;\nquantity<isq::work[J]> work = scalar_product(force, displacement);\n
    la::vector<quantity<si::metre>> displacement_1 = la::vector{1 * m, 2 * m, 3 * m};\nla::vector<quantity<si::metre>> displacement_2 = la::vector{2 * m, 1 * m, 0 * m};\nla::vector<quantity<si::metre>> displacement = displacement_1 + displacement_2;\nla::vector<quantity<si::newton>> force = la::vector{42 * N, 42 * N, 42 * N};\nquantity<si::joule> work = la::scalar_product(force, displacement);\n

    Of course, someone could argue that incorrect use of a vector product operation above would also be safe as it will not compile as the return type differs. Yes, it is true. However, please remember that there are more cases where errors may happen.

    For example, an external linear algebra library will not protect us from providing arguments to a vector product in an invalid order.

    Also, our work quantity will never be able to detect if what we are trying to assign to it is a result of a scalar product of two vector quantities of displacement and force, or maybe just some naive multiplication of scalar quantities that accidentally matched the dimensionality of the expected result.

    Please also remember that the quantity characters are not only about linear algebra. For example, in the case of complex quantities, we want to ensure that only:

    Mixing the above is a fatal error in power systems engineering.

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#implementation-challenges","title":"Implementation challenges","text":"

    I had planned to implement the above features for a few years now but never had enough time to do it. Now, I am close to finishing the work. However, I've discovered a few interesting issues on the way, and I have to solve them before putting my code on the mainline and releasing the next mp-units version.

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#modeling-magnitudes","title":"Modeling magnitudes","text":"

    Let's dig in a bit more into proper modelling of position vector and displacement quantities. First, we have to think to which scalar quantities their magnitude should convert to:

    Taking the above into account, we should refactor our tree of quantities of kind length into the following:

    flowchart TD\n    length[\"<b>length</b><br>[m]\"]\n    length --- width[\"<b>width</b> / <b>breadth</b>\"]\n    length --- height[\"<b>height</b> / <b>depth</b> / <b>altitude</b>\"]\n    width --- thickness[\"<b>thickness</b>\"]\n    width --- diameter[\"<b>diameter</b>\"]\n    width --- radius[\"<b>radius</b>\"]\n    radius --- radius_of_curvature[\"<b>radius_of_curvature</b>\"]\n    length --- path_length[\"<b>path_length</b>\"]\n    path_length --- distance[\"<b>distance</b>\"]\n    distance --- displacement[\"<b>displacement</b><br>{vector}\"]\n    distance --- radial_distance[\"<b>radial_distance</b>\"]\n    radial_distance --- position_vector[\"<b>position_vector</b><br>{vector}\"]\n    length --- wavelength[\"<b>wavelength</b>\"]

    Having the above, we can look a bit closer into how velocity and speed are defined in the ISQ:

    ISO 80000-3: Space and time

    velocity - vector quantity giving the rate of change of a position vector.

    speed - magnitude of the velocity.

    Change of a position vector is nothing else than a displacement. This means that velocity and speed can be defined as follows:

    inline constexpr struct velocity final : quantity_spec<displacement / duration> {} velocity;\ninline constexpr struct speed final : quantity_spec<magnitude(velocity)> {} speed;\n

    This is compatible with the ISQ definitions. However, we should check what it means from the engineering point of view. Let's assume that we want to calculate speed directly from a distance traveled and duration, without using any vector quantities like displacement or velocity:

    quantity<isq::distance[m]> distance = 42 * m;\nquantity<isq::duration[s]> duration = 2 * s;\n// quantity<isq::speed[m / s]> speed = distance / duration;  // Compile-time error\n

    The above does not compile because distance quantity is not implicitly convertible to magnitude(displacement). This is the same case as stating that not every length is a distance. We need to cast here explicitly. To fix it, we can do any of the below:

    quantity<isq::speed[m / s]> speed1 = isq::speed(distance / duration);\nquantity<isq::speed[m / s]> speed2 = magnitude(isq::displacement)(distance) / duration;\n

    Also, the following will work:

    quantity length_kind = 42 * m;\nquantity<isq::speed[m / s]> speed3 = length_kind / duration;\n

    If we do not specify a specific quantity type and just use an SI unit, then we deal with the kind of quantity. Such quantity can behave like any quantity from the hierarchy tree with the same character, so it is also the same as magnitude(isq::displacement).

    Question

    Is it good enough from the engineering and usability point of views? If you would like to share your thoughts, please provide your comments below the article.

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#more-about-displacement-and-position-vector","title":"More about displacement and position vector","text":"

    As we've stated above, a change of position vector is a displacement. Let's try to calculate it here:

    quantity pos1 = isq::position_vector(vector{1, 2} * m);\nquantity pos2 = isq::position_vector(vector{2, 3} * m);\nquantity q7 = pos2 - pos1;\n// quantity<isq::displacement[m], vector> displacement = q7;  // Compile-time error\n// quantity displacement = isq::displacement(q7);             // Compile-time error\nquantity displacement = quantity_cast<isq::displacement>(q7);\n

    Again, the above might be surprising and considered a usability issue. Let me describe why the code behaves like that.

    As of today, the result of an addition or subtraction of two quantities is their common quantity type. When subtracting two position vectors we end up with a position vector. Looking at the above hierarchy tree, we can easily see that position vector and displacement are on different branches. This prevents implicit and explicit conversions between those. The only one allowed to force such a conversion is an explicit cast.

    If we think more about it, this makes a lot of sense. Position vector is not a special case of displacement or vice versa. Those should not be convertible. We do not want the code to compile when we accidentally pass a position vector to the numerator of the equation for velocity, right? What does calculating the velocity for a position vector mean?

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#affine-spaces-within-quantity-trees","title":"Affine spaces within quantity trees","text":"

    Also, let's look at the type of variable q7. We know that subtracting two quantities of the same type results in a quantity of the same type. This is also the case when we do it for position vectors. We will see the same resulting type when we add two position vectors as well. But wait... What does it actually mean to add two position vectors?

    Looks familiar? Yes, we can clearly see that we are dealing with yet another case of the affine space. This time, it is hidden within the quantities hierarchy tree. This also means that adding a position vector and a displacement should result in a position vector. Let's try to do it:

    quantity q8 = pos1 + displacement;                       // Often a compile-time error\n

    Unfortunately, this often fails on the very first step, even before assigning the result to the position vector quantity. The reason for this is that in the hierarchy tree, the first common node for position vector and displacement is distance, which is a scalar quantity. Trying to use a vector representation type for a scalar quantity yields an error as a result of already existing checks described in the Representation types chapter.

    However, the code will compile if we use the same representation type for scalar and vector quantity (e.g., int or double may be used as a vector representation type for a well-known axis). In this case, we will end up with:

    // quantity<isq::position_vector[m], vector> pos3 = q8;       // Compile-time error\nquantity<isq::position_vector[m], vector> pos3 = isq::position_vector(q8);\n

    We need to convert a distance explicitly to a position vector quantity to move \"down\" over a branch in a hierarchy tree.

    It is important to note that there are more quantities that may behave the same. For example, altitude/height and time/duration may also form similar affine spaces. More similar examples can be found in other hierarchy trees.

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#extending-arithmetic-on-quantity-specifications","title":"Extending arithmetic on quantity specifications","text":"

    mp-units provided support for multiplication and division of quantity_spec from the beginning. It was needed to obtain derived quantities. Adding support for quantity characters also added special operations (e.g., magnitude(), scalar_product(), etc.) on quantity_spec arguments. If we want to support such affine space abstractions, we must also add support for addition and subtraction, which may yield different results.

    For example:

    static_assert(isq::length + isq::length == isq::length);\nstatic_assert(isq::height + isq::width == isq::length);\nstatic_assert(isq::altitude + isq::height == isq::altitude);\nstatic_assert(isq::height + isq::altitude == isq::altitude);\n\nstatic_assert(isq::length - isq::length == isq::length);\nstatic_assert(isq::height - isq::width == isq::length);\nstatic_assert(isq::altitude - isq::height == isq::altitude);\nstatic_assert(isq::altitude - isq::altitude == isq::height);\n

    Also, some operations should not compile. For example:

    // auto qs1 = isq::altitude + isq::altitude;  // Compile-time error\n// auto qs2 = isq::height - isq::altitude;    // Compile-time error\n
    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#defining-affine-space-abstractions-in-a-quantity_spec","title":"Defining affine space abstractions in a quantity_spec","text":"

    We can add support for the above by adding point_for<QuantitySpec> attribute to the quantity_spec definition:

    inline constexpr struct height final : quantity_spec<length> {} height;\ninline constexpr struct altitude final : quantity_spec<length, point_for<height>> {} altitude;\ninline constexpr struct displacement final : quantity_spec<distance, quantity_character::vector> {} displacement;\ninline constexpr struct position_vector final : quantity_spec<radial_distance, point_for<displacement>, quantity_character::vector> {} position_vector;\n

    Thanks to the above, the library always knows a \"delta\" quantity for a \"point\" type. I've implemented this logic, got great results, and thought I was done. But next, I realized that I need to update a few more things.

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#adding-support-to-quantity_point","title":"Adding support to quantity_point","text":"

    quantity_point is intended to model \"point\" quantities and return \"delta\" quantities on subtraction or by calling .quantity_from...() family of member functions. This is possible and can be done. I've finished most of the implementation already. However, two interesting questions arise:

    1. Should isq::altitude be reserved only for quantity_point and not available for \"regular\"\u00a0quantity types?
    2. Should isq::height apply only to quantity?

    I think that question #1 makes a lot of sense. If we realize that quantity always represents \"delta\" quantities, what would a quantity of isq::altitude mean? However, forcing the usage of quantity_point might be too strict here. Some users are not familiar or comfortable with this abstraction. Also, we can't multiply or divide quantity points.

    Question

    Does anyone know a derived quantity built with altitude or time instant? If so, please let me know in the comments, as limiting \"point\" quantity_spec to quantity_point would prevent forming such derived quantities.

    Question #2 is also interesting. However, in this case, I think that the answer should be \"NO\". I can imagine a series of height measurements. Every physical measurement can be modeled as a quantity_point, so a quantity_point of height might make sense.

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#opening-can-of-worms","title":"Opening can of worms","text":"

    So far, so good. I thought I was done here and could continue my work on symbolic expressions for vector and complex quantities. However, I've realized that I've opened a can of worms. What about the convertibility of quantity_spec? How should common_quantity_spec() behave?

    Let's start with conversions. It might seem easy. isq::altitude and isq::height should not be convertible to each other. But more questions arise:

    1. Should it be possible to quantity_cast from isq::altitude to isq::height or vice versa?
    2. Should isq::height be convertible to isq::length?
    3. Should isq::length be explicitly convertible to isq::height?
    4. Should isq::altitude be convertible to isq::length?
    5. Should isq::length be explicitly convertible to isq::altitude?

    The need for #1 will always probably mean an error in program logic, so quantity_cast could not work for such entities. This would be an exception to our conversion rules that always allow casting between branches of one tree.

    The answer to questions #2 and #3 is \"YES\".

    We might be tempted to say \"NO\" to questions #4 and #5 as isq::altitude is defined as \"point\" while isq::length is not specified as such. However, I've just realized that it is not the case.

    The proper answer to questions #4 and #5 is \"It depends\". If we are dealing with a quantity_point then converting from isq::altitude to isq::length or the other way around should work. However, it would probably be a bad idea for a quantity type.

    It turns out that common_quantity_spec() is similar. It is probably safe to state that it should not compile for isq::altitude and isq::height arguments. This means that we will not be able to compare such quantities as well. As those are different abstractions, preventing that might be an excellent idea.

    Again, it gets tricky if we consider passing isq::length and isq::altitude to it. For quantity_point it probably should work fine and fail to compile for quantity.

    The above means that to determine the conversion rules and common quantity specifications, we need to know the context in which the quantity_spec is being used. This sucks!

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#should-we-get-rid-of-a-quantity_point","title":"Should we get rid of a quantity_point?","text":"

    There are at least two ways of solving the above issue. In any case, we need to introduce a wrapper over the quantity_spec to denote it is being used in a \"point\" abstraction.

    A simpler solution could be implicitly amending the Reference provided to the quantity_point class template with point<...>. So, for example, we would have the following members in quantity_point<isq::altitude[m]>:

    This should work but might be a bit confusing as members of the class template would not exactly contain the types of template parameters.

    A better solution might be removing a dedicated quantity_point abstraction and providing both functionalities through the quantity class template. I still haven't figured out the best syntax. Please let me know if you have good ideas in the comments below. Here are some rough ideas:

    Before After quantity_spec quantity<si::metre> quantity<si::metre> kind_of<isq::length> quantity_point<si::metre> quantity<point<si::metre>> point<kind_of<isq::length>> quantity_point<si::metre, mean_sea_level> quantity<point<si::metre, mean_sea_level>> point<kind_of<isq::length>> quantity<isq::height[m]> quantity<isq::height[m]> isq::height quantity_point<isq::height[m]> quantity<point<isq::height[m]>> point<isq::height> quantity_point<isq::altitude[m]> quantity<point<isq::altitude[m]>> point<isq::altitude> quantity_point<isq::altitude[m], mean_sea_level> quantity<point<isq::altitude[m], mean_sea_level>> point<isq::altitude>

    I am still undecided about whether we should pursue this option, which would involve a huge design change in the library. It may even require bumping the library major version to V3.

    On the bright side, it would limit the number of abstractions in the library. It would also make the library more consistent with standards like ISO/IEC 80000, which talk about quantities and do not mention quantity points at all. This could also be useful before we start our work on the next big task - logarithmic quantities and units.

    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/","title":"Introducing absolute quantities","text":"

    This post introduces a new abstraction called an absolute quantity. It complements affine space abstractions (point and delta) and will most probably be a new default in the library when we release V3.

    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#affine-space-in-a-nutshell","title":"Affine space in a nutshell","text":"

    So far mp-units and other quantities and units libraries have been modeling two kinds of abstractions:

    1. Points (modeled with quantity_point class template)

      • can be interpolated,
      • can be subtracted,
      • can't be added,
      • can't be multiplied or divided by another quantity or scalar,
      • some of them could be specified as non-negative,
      • specified relative to some absolute or relative point origin,
      • conversion to offset units (e.g., degree Celsius) accounts for offset.

    2. Deltas (modeled with quantity class template)

      • can be interpolated,
      • can be subtracted,
      • can be added,
      • can be multiplied and divided by another quantity and scalar,
      • may be negative as there is always a chance that we will subtract a larger value from a smaller one,
      • don't use point origins in its definition,
      • conversion to offset units (e.g., degree Celsius) ignores the offset (just the conversion factor is used).

    Info

    More information on this subject can be found in the Affine Space chapter.

    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#issues","title":"Issues","text":"

    A current affine space implementation works well for many essential use cases. However, it also produces some issues.

    1. We can't print quantity points as, at least for today, we do not have the means to properly describe the user-provided origin in the text output.
    2. Quantity points are hard to use in physical equations to denote not-delta values.

    To make both of the above work, a user needs to convert the quantity point to quantity with either qp.quantity_from_zero() or qp.quantity_from(some_origin) member functions.

    quantity_point m1(2 * kg);\nquantity_point m2(3 * kg);\nquantity_point m = m1 + m2.quantity_from_zero();\nquantity d_v = 30 * km / h;\nquantity E_k = m.quantity_from_zero() * pow<2>(d_v) / 2;\n\nstd::cout << \"Mass: \" << m.quantity_from_zero() << \"\\n\";\nstd::cout << \"Velocity: \" << d_v << \"\\n\";\nstd::cout << \"Kinetic energy: \" << E_k.in<double>(J) << \"\\n\";\n

    This is quite inconvenient and is a common reason for avoiding quantity point abstraction in many equations in source code where it would be a good fit otherwise.

    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#absolute-quantities","title":"Absolute quantities","text":"

    Despite the above drawbacks, affine space points are necessary to model some abstractions (e.g., temperatures in degrees Celsius, tared mass measurements, altitudes above some reference point, etc.) and do it really well. Constrained affine space arithmetic (e.g., preventing accidental addition of points) also improves the safety of our programs. This is why it is a valuable abstraction and should be used more even often than now.

    To improve the user experience and open the doors for new features in the future, we are considering adding a third abstraction for absolute quantities. In terms of properties, an absolute quantity will lie between points and deltas.

    Feature Point Absolute Delta Interpolation Subtraction Addition Multiply/Divide May be non-negative Relative to origin Absolute & relative Measured against nothing/void Can use offset units Conversion to offset units With offset No offset Text output

    As we can see above, absolute quantities have only two limitations, and both are connected to the offset units' usage. They can't use those because they must remain absolute instead of being measured relative to some custom origin.

    Absolute quantities could be considered delta quantities that represent a whole -- the entire entity being measured. This is why we can represent a system mass by adding absolute masses of all system elements or a system energy by adding absolute temperatures of all the system elements.

    As those are more related to deltas than points, it is impossible to specify their origin points. This also allows us to print them, as we do not need any special text to describe their origin as they are always measured against nothing/void.

    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#interfaces-refactoring","title":"Interfaces refactoring","text":"

    As I mentioned in my previous post, we are seriously considering removing quantity_point class template and replacing it with a quantity_spec point wrapper. For example, quantity_point<isq::altitude[m]> will become quantity<point<isq::altitude[m]>>.

    I initially planned quantity<isq::mass> to be the same as quantity<delta<isq::mass>>, but it turns out that deltas probably should not be the default. It is consistent with how we write physical expressions on paper, right? Delta symbol (\u2206) is always \"verbose\" in physical equations, it would be nice for the C++ code to do the same. So, deltas will always need to be explicit.

    And this brings us to absolute quantities. They should actually be the default we are looking for. This is what we write as quantities in most of the physical equations. This is why we will not need any specifier to denote them.

    For example:

    inline constexpr struct tare final : relative_point_origin<quantity_point{2 * kg}> {} tare;\n\nquantity<point<isq::mass>>       m1(10 * kg);         // point quantity with an implicit point origin\nquantity<point<isq::mass, tare>> m2 = tare + 8 * kg;  // point quantity with an explicit relative point origin\nquantity<isq::mass> \u00a0 \u00a0 \u00a0 \u00a0      m3 = 15 * kg;        // absolute quantity (e.g., non-negative)\nquantity<delta<isq::mass>>       m13 = m1 - m3;       // delta quantity (e.g., may be negative)\nquantity<delta<isq::mass>>       m23 = m2 - m3;       // delta quantity (e.g., may be negative)\n

    With the above, the initial example may be refactored to:

    quantity m1 = 2 * kg;\nquantity m2 = 3 * kg;\nquantity m = m1 + m2;\nquantity d_v = delta<km / h>(30);\nquantity E_k = m * pow<2>(d_v) / 2;\n\nstd::cout << \"Mass: \" << m << \"\\n\";\nstd::cout << \"Velocity: \" << d_v << \"\\n\";\nstd::cout << \"Kinetic energy: \" << E_k.in<double>(J) << \"\\n\";\n
    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#arithmetic","title":"Arithmetic","text":"

    Affine space arithmetic is well-defined. However, we are adding a new type to the library that lands between points and deltas. This is why we must agree on the arithmetic for all possible combinations.

    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#addition","title":"Addition","text":"

    Absolute quantities are deltas against nothing so adding them to a point yields another point.

    Adding a delta to them yields a delta, as a delta may represent only a part of something and a whole, and a part is not a whole. The delta may also be negative and greater than the absolute quantity, which may yield a negative value. This is why delta is a good result here.

    Only adding whole non-negative entities of the system yields a system being expressed as an entire non-negative entity. This is why adding absolute quantities results in an absolute quantity.

    Lhs \\ Rhs Point Absolute Delta Point Point Point Absolute Point Absolute Delta Delta Point Delta Delta"},{"location":"blog/2025/06/16/introducing-absolute-quantities/#subtraction","title":"Subtraction","text":"

    Similarly, during subtraction, regular affine space arithmetics for deltas apply. Subtracting an absolute quantity from a point yields a point, and trying to do the opposite does not make physical sense.

    Subtracting two non-negative absolute quantities may yield a negative value if we subtract a larger one from the smaller one, so the result should be a delta. A similar result may be obtained by subtracting a delta from absolute quantity or absolute quantity from a delta.

    Lhs \\ Rhs Point Absolute Delta Point Delta Point Point Absolute Delta Delta Delta Delta Delta

    Info

    Based on the above assumptions, one of the lines of the below code can't compile:

    quantity temp1 = 270 * K;\nquantity temp2 = point<K>(300);\nquantity temp3 = temp2 - temp1;             // Point\n// quantity temp4 = temp1 - temp2;          // Compile-time error\nquantity temp5 = temp1 - temp2.absolute();  // Delta\n
    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#motivating-example","title":"Motivating example","text":"

    Let's consider a room with a table and two glasses filled with fluid on top of it. Let's also assume that we want to stack one on top of the other and treat them as a system we observe.

    // absolute quantities\nquantity<isq::height[cm]> glass1_height = 20 * cm;\nquantity<isq::height[cm]> glass2_height = 15 * cm;\n\n// delta quantities\nquantity<delta<isq::height>[cm]> fluid_level = 16 * cm;\n\n// point quantities\ninline constexpr struct floor_level final : absolute_point_origin<isq::height> floor_level;\nquantity<point<isq::height[cm], floor_level>> table_top = floor_level + 1 * m;\n\n// absolute results\nquantity system_height = glass1_height + glass2_height;\n\n// delta results\nquantity empty_height_res = glass1_height - fluid_level;\nquantity glass2_height_res = system_height - glass1_height;    // could result in an absolute quantity\nassert(glass2_height_res == glass2_height);\nquantity height_diff_res = glass2_height - glass1_height;      // but this one should definitely return delta\n\n// point results\nquantity<point<isq::height[cm], floor_level>> glass1_top = table_top + glass1_height;\nquantity point1 = glass1_top - glass1_height;\nassert(point1 == table_top);\n// quantity point2 = glass1_height - glass1_top; \u00a0 \u00a0          \u00a0// no sense - does not compile\n
    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#what-about-time","title":"What about time?","text":"

    Everything looks promising and nice for now. But let's look closer into the quantity of time. There is no way to measure its absolute value as we don't even know where (when?) the time axis starts... Only time points and time deltas (durations) make sense.

    The above raises a few questions:

    1. Does it mean that quantity<si::seconds> or quantity<isq::time[s]> should not compile?
    2. Should we require the user to always state quantity<delta<si::seconds>> or \u00a0 \u00a0quantity<delta<isq::time[s]>>? This would be consistent with physical equations but more verbose in the source code.
    3. Should the syntax 40 * s be disallowed or should it implicitly createquantity<delta<si::seconds>> instead of quantity<si::seconds>?
    4. A somehow similar case might be the length quantity as there is no one well-established zero origin that serves for all length measurements. However, asking the users always to provide a delta specifier for length would probably be an overkill.

    As you can see, I do not yet have good answers to the above problems yet. Please feel welcome to share some feedback on this.

    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#new-opportunities","title":"New opportunities","text":"

    The new syntax simplifies API as one quantity class template will now serve all quantity variations (possibly even more in the future). It also allows us to model quantities that were impossible to express before without some workarounds.

    For example, we can now correctly calculate Carnot engine efficiency with any of the following:

    quantity temp_cold = 300. * K;\nquantity temp_hot = 500. * K;\nquantity carnot_eff_1 = 1. - temp_cold / temp_hot;\nquantity carnot_eff_2 = (temp_hot - temp_cold) / temp_hot;\n

    In the above code, we can easily create absolute or delta values of temperatures and do arithmetics on them. Previously, we had to create deltas from both points artificially with:

    quantity temp_cold = point<K>(300.);\nquantity temp_hot = point<K>(500.);\nquantity carnot_eff_1 = 1. - temp_cold.quantity_from_zero() / temp_hot.quantity_from_zero();\nquantity carnot_eff_2 = (temp_hot - temp_cold) / temp_hot.quantity_from_zero();\n

    It worked but was far from being physically pure and pretty.

    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#summary","title":"Summary","text":"

    We believe that adding absolute quantities will be a significant improvement in the library that will allow us to model physical equations in a terser, more correct, easier to write, understand, and maintain way.

    We plan to deliver the features mentioned in this post as a part of mp-units V3.

    Please share your feedback.

    "},{"location":"blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/","title":"International System of Quantities (ISQ): Part 1 - Introduction","text":"

    This post starts a series of articles about the International System of Quantities (ISQ). In this series, we will describe:

    "},{"location":"blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/#articles-from-this-series","title":"Articles from this series","text":""},{"location":"blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/#terms-and-definitions","title":"Terms and Definitions","text":"

    From our experience, many people, including experts in the domain, often tend to name things differently, or sometimes they use the same term while having a different meaning in mind. This is why it is essential to stick to one well-defined glossary of terms for metrology.

    The mp-units project consistently uses the official metrology vocabulary defined by the ISO and BIPM:

    The above are identical and contain the same set of definitions. We provide both to point out that the biggest institutions in standardizing metrology agree on the same vocabulary.

    "},{"location":"blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/#systems-of-quantities-vs-systems-of-units","title":"Systems of Quantities vs Systems of Units","text":"

    Here are the official definitions from our vocabulary:

    System of quantities

    A system of quantities is a set of quantities together with a set of noncontradictory equations relating those quantities.

    System of units

    A system of units is a set of base units and derived units, together with their multiples and submultiples, defined in accordance with given rules, for a given system of quantities.

    From the definition above, we can find out that the systems of quantities and units form a hierarchy:

    flowchart TD\n    system_of_quantities[\"System of Quantities\"]\n    system_of_quantities --- system_of_units1[System of Units #1]\n    system_of_quantities --- system_of_units2[System of Units #2]\n    system_of_quantities --- system_of_units3[System of Units #3]

    System of quantities defines quantities commonly used in engineering (e.g., length, time, mass, speed, energy, power, etc.) and relations between them. It does not assign any specific units to those quantities, though.

    Systems of units are the ones that assign units of measurement to quantities from a specific system of quantities they chose to model. Different systems of units are free to chose whatever they find suitable for specific quantities and do not have to be consistent/compatible with other such systems. For example:

    Both systems of units above agree on the unit of time, but chose different units for other quantities. In the above example, SI chose a non-prefixed unit of metre for a base quantity of length while CGS chose a scaled centimetre. On the other hand, SI chose a scaled kilogram over the gram used in the CGS. Those decisions also result in a need for different coherent units for derived quantities. For example:

    Quantity SI CGS length metre (m) centimetre (cm) mass kilogram (kg) gram (g) time second (s) second (s) force newton (N) dyne energy joule (J) erg pressure pascal (Pa) barye

    Often, there is no way to state which one is correct or which one is wrong. Each system of units has the freedom to choose whichever unit suits its engineering requirements and constraints the best for a specific quantity.

    "},{"location":"blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/#isq-vs-si","title":"ISQ vs SI","text":"

    Some of the systems of quantities and units have been used more over the years and have become more popular than others. Here are the official descriptions of the most popular systems used in engineering today:

    International System of Quantities (ISQ)

    The International System of Quantities (ISQ) is a system of quantities based on the seven base quantities: length, mass, time, electric current, thermodynamic temperature, amount of substance, and luminous intensity.

    International System of Units (SI)

    The International System of Units (SI) is a system of units, based on the International System of Quantities, their names and symbols, including a series of prefixes and their names and symbols, together with rules for their use, adopted by the General Conference on Weights and Measures (CGPM).

    "},{"location":"blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/#the-international-system-of-quantities-isq-standardization","title":"The International System of Quantities (ISQ) standardization","text":"

    The set of quantities constituting the ISQ is defined in the series of ISO 80000 and IEC 80000 standards under the general title \"Quantities and units\".

    ISO 80000:

    IEC 80000:

    "},{"location":"blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/#to-be-continued","title":"To be continued...","text":"

    In the next part of this series, we will describe typical issues with libraries that do not model systems of quantities.

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/","title":"International System of Quantities (ISQ): Part 2 - Problems when ISQ is not used","text":"

    This article is the next one in our series about the ISQ. After introducing the basic terms and systems, this article will talk about the issues we face when we base the quantities and units library on just units or dimensions.

    Note

    The issues described in this article do not apply to the mp-units library. Its interfaces, even if when we decide only to use simple quantities that only use units, those are still backed up by quantity kinds under the framework's hood.

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#articles-from-this-series","title":"Articles from this series","text":""},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#limitations-of-units-only-solutions","title":"Limitations of units-only solutions","text":"

    Units-only is not a good design for a quantities and units library. It works to some extent, but plenty of use cases can't be addressed, and for those that somehow work, we miss important safety improvements provided by additional abstractions in this article series.

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#no-way-to-specify-a-quantity-type-in-generic-interfaces","title":"No way to specify a quantity type in generic interfaces","text":"

    A common requirement in the domain is to write unit-agnostic generic interfaces. For example, let's try to implement a generic avg_speed function template that takes a quantity of any unit and produces the result. If we call it with distance in km and time in h, we will get km/h as a result, but if we call it with mi and h, we expect mi/h to be returned.

    template<Unit auto U1, typename Rep1, Unit auto U2, typename Rep2>\nauto avg_speed(quantity<U1, Rep1> distance, quantity<U2, Rep2> time)\n{\n  return distance / time;\n}\n\nquantity speed = avg_speed(120 * km, 2 * h);\n

    This function works but does not provide any type safety to the users. The function arguments can be easily reordered on the call site. Also, we do not get any information about the return type of the function or any safety measures to ensure that the function logic actually returns a quantity of speed.

    To improve safety, with a units-only library, we have to write the function in the following way:

    template<typename Rep1, typename Rep2>\nquantity<si::metre / si::second, decltype(Rep1{} / Rep2{})> avg_speed(quantity<si::metre, Rep1> distance,\n                                                                      quantity<si::second, Rep2> time)\n{\n  return distance / time;\n}\n\navg_speed(120 * km, 2 * h).in(km / h);\n

    Despite being safer, the above code decreased the performance because we always pay for the conversion at the function's input and output.

    Moreover, in a good library, the above code should not compile. The reason for this is that even though the conversion from km to m and from h to s is considered value-preserving, it is not true in the opposite direction. When we try to convert the result stored in an integral type from the unit of m/s to km/h, we will inevitably lose some data.

    We could try to provide concepts like ScaledUnitOf<si::metre> that would take a set of units while trying to constrain them somehow, but it leads to even more problems with the unit definitions. For example, are Hz and Bq just scaled versions of 1/s? If we constrain the interface to just prefixed units, then litre and a cubic metre or kilometre and mile will be incompatible. What about radian and steradian or a litre per 100 kilometre (popular unit of a fuel consumption) and a squared metre? Should those be compatible?

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#disjoint-units-of-the-same-quantity-type-do-not-work","title":"Disjoint units of the same quantity type do not work","text":"

    Sometimes, we need to define several units describing the same quantity but which should not convert to each other in the library's framework. A typical example here is currency. A user may want to define EURO and USD as units of currency, so both of them can be used for such quantities. However, it is impossible to predefine one fixed conversion factor for those, as a currency exchange rate varies over time, and the library's framework can't provide such an information as an input to the built-in conversion function. User's application may have more information in this domain and handle such a conversion at runtime with custom logic (e.g., using an additional time point function argument). If we would like to model that in a unit-only solution, how can we specify that EURO and USD are units of quantities of currency, but are not convertible to each other?

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#dimensions-to-the-rescue","title":"Dimensions to the rescue?","text":"

    To resolve the above issues, most of the libraries on the market introduce dimension abstraction. Thanks to that, we could solve the first issue of the previous chapter with:

    QuantityOf<dim_speed> auto avg_speed(QuantityOf<dim_length> auto distance,\n                                     QuantityOf<dim_time> auto time)\n{\n  return distance / time;\n}\n

    and the second one by specifying that both EURO and USD are units of dim_currency. This is a significant improvement but still has some issues.

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#limitations-of-dimensions","title":"Limitations of dimensions","text":"

    Let's first look at the above solution again. A domain expert seeing this code will immediately say there is no such thing as a speed dimension. The ISQ specifies only 7 dimensions with unique symbols assigned, and the dimensions of all the ISQ quantities are created as a vector product of those. For example, a quantity of speed has a dimension of \\(L^1T^{-1}\\). So, to be physically correct, the above code should be rewritten as:

    QuantityOf<dim_length / dim_time> auto avg_speed(QuantityOf<dim_length> auto distance,\n                                                 QuantityOf<dim_time> auto time)\n{\n  return distance / time;\n}\n

    Most of the libraries on the market ignore this fact and try to model distinct quantities through their dimensions, giving a false sense of safety. A dimension is not enough to describe a quantity. This has been known for a long time now. The \"Measurement Data (Archive Report)\" report from 1996 says explicitly:

    Measurement Data (Archive Report)

    Dimensional analysis does not adequately model the semantics of measurement data.

    In the following chapters, we will see a few use cases that can't be solved with an approach that only relies on units or dimensions.

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#si-units-of-quantities-of-the-same-dimension-but-different-kinds","title":"SI units of quantities of the same dimension but different kinds","text":"

    The SI provides several units for distinct quantities of the same dimension but different kinds. For example:

    There are many more similar examples in the ISO/IEC 80000 series. For example, storage capacity quantity can be measured in units of one, bit, octet, and byte.

    The above conflicts can't be solved with dimensions, and they yield many safety issues. For example, we can ask ourselves what should be the result of the following:

    1. quantity q = 1 * Hz + 1 * Bq;
    2. quantity<Gy> q = 42 * Sv;
    3. bool b = (1 * rad + 1 * bit) == 2 * sr;

    None of the above code should compile, but most of the libraries on the market happily accept it and provide meaningless results. Some of them decide not to define one or more of the above units at all to avoid potential safety issues. For example, the Au library does not define Sv to avoid mixing it up with Gy.

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#derived-quantities-of-the-same-dimension-but-different-kinds","title":"Derived quantities of the same dimension but different kinds","text":"

    Even if some quantities do not have a specially assigned unit, they may still have a totally different physical meaning even if they share the same dimension:

    Again, we don't want to accidentally mix those.

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#various-quantities-of-the-same-dimension-and-kinds","title":"Various quantities of the same dimension and kinds","text":"

    Even if we somehow address all the above, there are plenty of use cases that still can't be safely implemented with such abstractions.

    Let's consider that we want to implement a freight transport application to position cargo in the container. In majority of the products on the market we will end up with something like:

    class Box {\n  length length_;\n  length width_;\n  length height_;\npublic:\n  Box(length l, length w, length h): length_(l), width_(w), height_(h) {}\n  area floor() const { return length_ * width_; }\n  // ...\n};\n
    Box my_box(2 * m, 3 * m, 1 * m);\n

    Such interfaces are not much safer than just using plain fundamental types (e.g., double). One of the main reasons of using a quantities and units library was to introduce strong-type interfaces to prevent such issues. In this scenario, we need to be able to discriminate between length, width, and height of the package.

    A similar but also really important use case is in aviation. The current altitude is a totally different quantity than the distance to the destination. The same is true for forward speed and sink rate. We do not want to accidentally mix those.

    When we deal with energy, we should be able to implicitly construct it from a proper product of any mass, length, and time. However, when we want to calculate gravitational potential energy, we may not want it to be implicitly initialized from any expression of matching dimensions. Such an implicit construction should be allowed only if we multiply a mass with acceleration of free fall and height. All other conversions should have an explicit annotation to make it clear that something potentially unsafe is being done in the code. Also, we should not be able to assign a potential energy to a quantity of kinetic energy. However, both of them (possibly accumulated with each other) should be convertible to a mechanical energy quantity.

    mass m = 1 * kg;\nlength l = 1 * m;\ntime t = 1 * s;\nacceleration_of_free_fall g = 9.81 * m / s2;\nheight h = 1 * m;\nspeed v = 1 * m / s;\nenergy e = m * pow<2>(l) / pow<2>(t);                     // OK\npotential_energy ep1 = e;                                 // should not compile\npotential_energy ep2 = static_cast<potential_energy>(e);  // OK\npotential_energy ep3 = m * g * h;                         // OK\nkinetic_energy ek1 = m * pow<2>(v) / 2;                   // OK\nkinetic_energy ek2 = ep3 + ek1;                           // should not compile\nmechanical_energy me = ep3 + ek1;                         // OK\n

    Yet another example comes from the audio industry. In the audio software, we want to treat specific counts (e.g., beats, samples) as separate quantities. We could assign dedicated base dimensions to them. However, if we divide them by duration, we should obtain a quantity convertible to frequency and even be able to express the result in a unit of Hz. With the dedicated dimensions approach, this wouldn't work as the dimension of frequency is just \\(T^{-1}\\), which would not match the results of our dimensional equations. This is why we can't assign dedicated dimensions to such counts.

    The last example that we want to mention here comes from finance. This time, we need to model currency volume as a special quantity of currency. currency volume can be obtained by multiplying currency by the dimensionless market quantity. Of course, both currency and currency volume should be expressed in the same units (e.g., USD).

    None of the above scenarios can be addressed with just units and dimensions. We need a better abstraction to safely implement them.

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#to-be-continued","title":"To be continued...","text":"

    In the next part of this series, we will introduce the main ideas behind the International System of Quantities and describe how we can model it in the programming language.

    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/","title":"International System of Quantities (ISQ): Part 3 - Modeling ISQ","text":"

    The physical units libraries on the market typically only focus on modeling one or more systems of units. However, as we have learned, this is not the only system kind to model. Another, and maybe even more important, is a system of quantities. The most important example here is the International System of Quantities (ISQ) defined by ISO/IEC 80000.

    This article continues our series about the International System of Quantities. This time, we will learn about the main ideas behind the ISQ and describe how it can be modelled in a programming language.

    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#articles-from-this-series","title":"Articles from this series","text":""},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#dimension-is-not-enough-to-describe-a-quantity","title":"Dimension is not enough to describe a quantity","text":"

    Most of the products on the market are aware of physical dimensions. However, a dimension is not enough to describe a quantity. Let's repeat briefly some of the problems described in more detail in the previous article. For example, let's see the following implementation:

    class Box {\n  area base_;\n  length height_;\npublic:\n  Box(length l, length w, length h) : base_(l * w), height_(h) {}\n  // ...\n};\n\nBox my_box(2 * m, 3 * m, 1 * m);\n

    How do you like such an interface? It turns out that in most existing strongly-typed libraries this is often the best we can do.

    Another typical question many users ask is how to deal with work and torque. Both of those have the same dimension but are distinct quantities.

    A similar issue is related to figuring out what should be the result of:

    auto res = 1 * Hz + 1 * Bq + 1 * Bd;\n

    where:

    All of those quantities have the same dimension, namely \\(\\mathsf{T}^{-1}\\), but probably it is not wise to allow adding, subtracting, or comparing them, as they describe vastly different physical properties.

    If the above example seems too abstract, let's consider Gy (gray - unit of absorbed dose) and Sv (sievert - unit of dose equivalent), or radian and steradian. All of those quantities have the same dimensions.

    Another example here is fuel consumption (fuel volume divided by distance, e.g., 6.7 l/100km) and an area. Again, both have the same dimension \\(\\mathsf{L}^{2}\\), but probably it wouldn't be wise to allow adding, subtracting, or comparing a fuel consumption of a car and the area of a football field. Such an operation does not have any physical sense and should fail to compile.

    It turns out that the above issues can't be solved correctly without proper modeling of a system of quantities.

    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#quantities-of-the-same-kind","title":"Quantities of the same kind","text":"

    As it was described in the previous article, dimension is not enough to describe a quantity. We need a better abstraction to ensure the safety of our calculations. It turns out that ISO/IEC 80000 comes with the answer:

    ISO 80000-1:2009

    ISO Guide also explicitly states:

    ISO Guide

    Measurement units of quantities of the same quantity dimension may be designated by the same name and symbol even when the quantities are not of the same kind. For example, joule per kelvin and J/K are respectively the name and symbol of both a measurement unit of heat capacity and a measurement unit of entropy, which are generally not considered to be quantities of the same kind. However, in some cases special measurement unit names are restricted to be used with quantities of specific kind only. For example, the measurement unit \u2018second to the power minus one\u2019 (1/s) is called hertz (Hz) when used for frequencies and becquerel (Bq) when used for activities of radionuclides. As another example, the joule (J) is used as a unit of energy, but never as a unit of moment of force, i.e. the newton metre (N \u00b7 m).

    The above quotes from ISO provide answers to all the issues mentioned above and in the previous article.

    More than one quantity may be defined for the same dimension:

    Two quantities can't be added, subtracted, or compared unless they belong to the same kind. As frequency, activity, and modulation rate are of different kinds, the expression provided above should not compile.

    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#system-of-quantities-is-not-only-about-kinds","title":"System of quantities is not only about kinds","text":"

    ISO/IEC 80000 specifies hundreds of different quantities. Plenty of various kinds are provided, and often, each kind contains more than one quantity. It turns out that such quantities form a hierarchy of quantities of the same kind.

    For example, here are all quantities of the kind length provided in the ISO 80000-3:

    flowchart TD\n    length[\"<b>length</b><br>[m]\"]\n    length --- width[\"<b>width</b> / <b>breadth</b>\"]\n    length --- height[\"<b>height</b> / <b>depth</b> / <b>altitude</b>\"]\n    width --- thickness[\"<b>thickness</b>\"]\n    width --- diameter[\"<b>diameter</b>\"]\n    width --- radius[\"<b>radius</b>\"]\n    length --- path_length[\"<b>path_length</b>\"]\n    path_length --- distance[\"<b>distance</b>\"]\n    distance --- radial_distance[\"<b>radial_distance</b>\"]\n    length --- wavelength[\"<b>wavelength</b>\"]\n    length --- displacement[\"<b>displacement</b><br>{vector}\"]\n    displacement --- position_vector[\"<b>position_vector</b>\"]\n    radius --- radius_of_curvature[\"<b>radius_of_curvature</b>\"]

    Each of the above quantities expresses some kind of length, and each can be measured with meters, which is the unit defined by the SI for quantities of length. However, each has different properties, usage, and sometimes even a different character (position vector and displacement are vector quantities).

    Forming such a hierarchy helps us define arithmetics and conversion rules for various quantities of the same kind.

    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#converting-between-quantities-of-the-same-kind","title":"Converting between quantities of the same kind","text":"

    Based on the hierarchy above, we can define the following quantity conversion rules:

    1. Implicit conversions

      • Every width is a length.
      • Every radius is a width.
      static_assert(implicitly_convertible(isq::width, isq::length));\nstatic_assert(implicitly_convertible(isq::radius, isq::length));\nstatic_assert(implicitly_convertible(isq::radius, isq::width));\n

      Implicit conversions are allowed on copy-initialization:

      void foo(quantity<isq::length[m]> q);\n
      quantity<isq::width[m]> q1 = 42 * m;\nquantity<isq::length[m]> q2 = q1;  // implicit quantity conversion\nfoo(q1);                           // implicit quantity conversion\n

    2. Explicit conversions

      • Not every length is a width.
      • Not every width is a radius.
      static_assert(!implicitly_convertible(isq::length, isq::width));\nstatic_assert(!implicitly_convertible(isq::length, isq::radius));\nstatic_assert(!implicitly_convertible(isq::width, isq::radius));\nstatic_assert(explicitly_convertible(isq::length, isq::width));\nstatic_assert(explicitly_convertible(isq::length, isq::radius));\nstatic_assert(explicitly_convertible(isq::width, isq::radius));\n

      Explicit conversions are forced by passing the quantity to a call operator of a quantity_spec type:

      void foo(quantity<isq::height[m]> q);\n
      quantity<isq::length[m]> q1 = 42 * m;\nquantity<isq::height[m]> q2 = isq::height(q1);  // explicit quantity conversion\nfoo(isq::height(q1));                           // explicit quantity conversion\n

    3. Explicit casts

      • height is never a width, and vice versa.
      • Both height and width are quantities of kind length.
      static_assert(!implicitly_convertible(isq::height, isq::width));\nstatic_assert(!explicitly_convertible(isq::height, isq::width));\nstatic_assert(castable(isq::height, isq::width));\n

      Explicit casts are forced with a dedicated quantity_cast function:

      void foo(quantity<isq::height[m]> q);\n
      quantity<isq::width[m]> q1 = 42 * m;\nquantity<isq::height[m]> q2 = quantity_cast<isq::height>(q1);  // explicit quantity cast\nfoo(quantity_cast<isq::height>(q1));                           // explicit quantity cast\n

    4. No conversion

      • time has nothing in common with length.
      static_assert(!implicitly_convertible(isq::time, isq::length));\nstatic_assert(!explicitly_convertible(isq::time, isq::length));\nstatic_assert(!castable(isq::time, isq::length));\n

      Even the explicit casts will not force such a conversion:

      void foo(quantity<isq::length[m]>);\n
      quantity<isq::length[m]> q1 = 42 * s;    // Compile-time error\nfoo(quantity_cast<isq::length>(42 * s)); // Compile-time error\n
    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#comparing-adding-and-subtracting-quantities-of-the-same-kind","title":"Comparing, adding, and subtracting quantities of the same kind","text":"

    ISO/IEC 80000 explicitly states that width and height are quantities of the same kind, and as such they:

    This means that we should be allowed to compare any quantities from the same tree (as long as their underlying representation types are comparable):

    static_assert(isq::radius(1 * m) == isq::height(1 * m));\n

    Also, based on our hierarchy above, the only reasonable result of 1 * width + 1 * height is 2 * length, where the result of length is known as a common quantity type. A result of such an equation is always the first common node in a hierarchy tree of the same kind. For example:

    static_assert((isq::width(1 * m) + isq::height(1 * m)).quantity_spec == isq::length);\nstatic_assert((isq::thickness(1 * m) + isq::radius(1 * m)).quantity_spec == isq::width);\nstatic_assert((isq::distance(1 * m) + isq::path_length(1 * m)).quantity_spec == isq::path_length);\n
    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#modeling-a-quantity-kind","title":"Modeling a quantity kind","text":"

    In the quantities and units library, we also need an abstraction describing an entire family of quantities of the same kind. Such quantities have not only the same dimension but also can be expressed in the same units.

    To annotate a quantity to represent its kind (and not just a hierarchy tree's root quantity) we introduced a kind_of<> specifier. For example, to express any quantity of length, we need to type kind_of<isq::length>.

    Important

    isq::length and kind_of<isq::length> are two different things.

    Such an entity behaves as any quantity of its kind. This means that it is implicitly convertible to any quantity in a tree.

    static_assert(!implicitly_convertible(isq::length, isq::height));\nstatic_assert(implicitly_convertible(kind_of<isq::length>, isq::height));\n

    Additionally, the result of operations on quantity kinds is also a quantity kind:

    static_assert(same_type<kind_of<isq::length> / kind_of<isq::time>, kind_of<isq::length / isq::time>>);\n

    However, if at least one equation's operand is not a quantity kind, the result becomes a \"strong\" quantity where all the kinds are converted to the hierarchy tree's root quantities:

    static_assert(!same_type<kind_of<isq::length> / isq::time, kind_of<isq::length / isq::time>>);\nstatic_assert(same_type<kind_of<isq::length> / isq::time, isq::length / isq::time>);\n

    Info

    Only a root quantity from the hierarchy tree or the one marked with is_kind specifier in the quantity_spec definition can be put as a template parameter to the kind_of specifier. For example, kind_of<isq::width> will fail to compile. However, we can call get_kind(q) to obtain a kind of any quantity:

    static_assert(get_kind(isq::width) == kind_of<isq::length>);\n
    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#how-do-systems-of-units-benefit-from-the-isq-and-quantity-kinds","title":"How do systems of units benefit from the ISQ and quantity kinds?","text":"

    Modeling a system of units is the most essential feature and a selling point of every physical units library. Thanks to that, the library can protect users from assigning, adding, subtracting, or comparing incompatible units and provide automated conversion factors between various compatible units.

    Probably all the libraries in the wild model the SI (or at least most of it), and many of them provide support for additional units belonging to various other systems (e.g., imperial).

    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#systems-of-units-are-based-on-systems-of-quantities","title":"Systems of units are based on systems of quantities","text":"

    Systems of quantities specify a set of quantities and equations relating to those quantities. Those equations do not take any unit or a numerical representation into account at all. In order to create a quantity, we need to add those missing pieces of information. This is where a system of units kicks in.

    The SI is explicitly stated to be based on the ISQ. Among others, it defines seven base units, one for each base quantity of ISQ. In the library, this is expressed by associating a quantity kind to a unit being defined:

    inline constexpr struct metre final : named_unit<\"m\", kind_of<isq::length>> {} metre;\n

    The kind_of<isq::length> above states explicitly that this unit has an associated quantity kind. In other words, si::metre (and scaled units based on it) can be used to express the amount of any quantity of kind length.

    Note

    For some systems of units (e.g., natural units), a unit may not have an associated quantity type. For example, if we define the speed of light constant as c = 1, we can define a system where both length and time will be measured in seconds, and speed will be a quantity measured with the unit one. In such case, the definition will look as follows:

    inline constexpr struct second final : named_unit<\"s\"> {} second;\n
    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#constraining-a-derived-unit-to-work-only-with-a-specific-derived-quantity","title":"Constraining a derived unit to work only with a specific derived quantity","text":"

    Some derived units are valid only for specific derived quantities. For example, SI specifies both hertz and becquerel derived units with the same unit equation \\(s^{-1}\\). However, it also explicitly states:

    SI

    The hertz shall only be used for periodic phenomena and the becquerel shall only be used for stochastic processes in activity referred to a radionuclide.

    This is why it is important for the library to allow constraining such units to be used only with a specific quantity kind:

    inline constexpr struct hertz final : named_unit<\"Hz\", one / second, kind_of<isq::frequency>> {} hertz;\ninline constexpr struct becquerel final : named_unit<\"Bq\", one / second, kind_of<isq::activity>> {} becquerel;\n

    With the above, hertz can only be used for frequencies, while becquerel should only be used for quantities of activity:

    quantity<isq::frequency[Hz]> q1 = 60 * Bq;   // Compile-time error\nquantity<isq::activity[Hz]> q2;              // Compile-time error\nquantity<isq::frequency[Hz]> q3 = 60 * Hz;   // OK\nstd::cout << q3.in(Bq) << \"\\n\";              // Compile-time error\n

    We know already that quantities of different kinds can't be compared, added, and subtracted. The following equation will not compile thanks to constraining derived units to be valid for specific kinds only:

    auto q = 1 * Hz + 1 * Bq;   // Fails to compile\n

    All of the above features improve the safety of our library and the products that are using it.

    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#to-be-continued","title":"To be continued...","text":"

    In the next part of this series, we will present how we can implement our ISQ model in a C++ programming language and we will point out some of the first issues that stand in our way.

    "},{"location":"blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/","title":"International System of Quantities (ISQ): Part 4 - Implementing ISQ","text":"

    Up until now, we have introduced the International System of Quantities and described how we can model its main aspects. This article will present how to implement those models in a programming language, and we will point out some of the first issues that stand in our way.

    In the previous article, we have already introduced a notion of quantity kind, provided kind_of<> specifier, and described how it helps in the modeling of the system of units (e.g., SI).

    Now, it is time to see how we can implement hierarchies of quantities of the same kind.

    "},{"location":"blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/#articles-from-this-series","title":"Articles from this series","text":""},{"location":"blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/#modeling-a-hierarchy-of-kind-length","title":"Modeling a hierarchy of kind length","text":"

    First, let's start with something easy - hierarchy of kind length. ISO 80000-3 does a good job of describing all relations between quantities in this case.

    We've seen this tree already:

    flowchart TD\n    length[\"<b>length</b><br>[m]\"]\n    length --- width[\"<b>width</b> / <b>breadth</b>\"]\n    length --- height[\"<b>height</b> / <b>depth</b> / <b>altitude</b>\"]\n    width --- thickness[\"<b>thickness</b>\"]\n    width --- diameter[\"<b>diameter</b>\"]\n    width --- radius[\"<b>radius</b>\"]\n    length --- path_length[\"<b>path_length</b>\"]\n    path_length --- distance[\"<b>distance</b>\"]\n    distance --- radial_distance[\"<b>radial_distance</b>\"]\n    length --- wavelength[\"<b>wavelength</b>\"]\n    length --- displacement[\"<b>displacement</b><br>{vector}\"]\n    displacement --- position_vector[\"<b>position_vector</b>\"]\n    radius --- radius_of_curvature[\"<b>radius_of_curvature</b>\"]

    This is how we can model it in C++:

    inline constexpr struct dim_length final          : base_dimension<\"L\"> {} dim_length;\n\ninline constexpr struct length final              : quantity_spec<dim_length> {} length;\ninline constexpr struct width final               : quantity_spec<length> {} width;\ninline constexpr auto breadth = width;\ninline constexpr struct height final              : quantity_spec<length> {} height;\ninline constexpr auto depth = height;\ninline constexpr auto altitude = height;\ninline constexpr struct thickness final           : quantity_spec<width> {} thickness;\ninline constexpr struct diameter final            : quantity_spec<width> {} diameter;\ninline constexpr struct radius final              : quantity_spec<width> {} radius;\ninline constexpr struct radius_of_curvature final : quantity_spec<radius> {} radius_of_curvature;\ninline constexpr struct path_length final         : quantity_spec<length> {} path_length;\ninline constexpr auto arc_length = path_length;\ninline constexpr struct distance final            : quantity_spec<path_length> {} distance;\ninline constexpr struct radial_distance final     : quantity_spec<distance> {} radial_distance;\ninline constexpr struct wavelength final          : quantity_spec<length> {} wavelength;\ninline constexpr struct displacement final        : quantity_spec<length, quantity_character::vector> {} displacement;\ninline constexpr struct position_vector final     : quantity_spec<displacement> {} position_vector;\n

    Thanks to the expressivity and power of C++ templates, we can specify all quantity properties in one line of code. In the above code:

    Note

    Some quantities may be specified to have complex scalar, vector, or tensor character (e.g., displacement). The quantity character can be set with the last parameter of quantity_spec.

    "},{"location":"blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/#modeling-a-hierarchy-of-kind-energy","title":"Modeling a hierarchy of kind energy","text":"

    Base quantities are simple. It is more complicated when we start modeling derived quantities. Let's try to model the hierarchy for energy.

    When we look into the ISO/IEC 80000 standards, this task immediately stops being as easy as the previous one. Derived quantity equations often do not automatically form a hierarchy tree, and ISO/IEC standards do not provide a clear answer to inter-quantity dependencies. This is why it is often not obvious what such a tree should look like.

    Even more, ISO explicitly states:

    ISO/IEC Guide 99

    The division of \u2018quantity\u2019 according to \u2018kind of quantity\u2019 is, to some extent, arbitrary.

    Let's try anyway. The below presents some arbitrary hierarchy of derived quantities of kind energy:

    flowchart TD\n    energy[\"<b>energy</b><br><i>(mass * length<sup>2</sup> / time<sup>2</sup>)</i><br>[J]\"]\n    energy --- mechanical_energy[\"<b>mechanical_energy</b>\"]\n    mechanical_energy --- potential_energy[\"<b>potential_energy</b>\"]\n    potential_energy --- gravitational_potential_energy[\"<b>gravitational_potential_energy</b><br><i>(mass * acceleration_of_free_fall * height)</i>\"]\n    potential_energy --- elastic_potential_energy[\"<b>elastic_potential_energy</b><br><i>(spring_constant * amount_of_compression<sup>2</sup>)</i>\"]\n    mechanical_energy --- kinetic_energy[\"<b>kinetic_energy</b><br><i>(mass * speed<sup>2</sup>)</i>\"]\n    energy --- enthalpy[\"<b>enthalpy</b>\"]\n    enthalpy --- internal_energy[\"<b>internal_energy</b> / <b>thermodynamic_energy</b>\"]\n    internal_energy --- Helmholtz_energy[\"<b>Helmholtz_energy</b> / <b>Helmholtz_function</b>\"]\n    enthalpy --- Gibbs_energy[\"<b>Gibbs_energy</b> / <b>Gibbs_function</b>\"]\n    energy --- active_energy[\"<b>active_energy</b>\"]

    As we can see above, besides what we've already seen for length hierarchy, derived quantities may provide specific recipes that can be used to create them implicitly:

    And here is the C++ code for it:

    inline constexpr struct energy final                         : quantity_spec<mass* pow<2>(length) / pow<2>(time)> {} energy;\ninline constexpr struct mechanical_energy final              : quantity_spec<energy> {} mechanical_energy;                                                            // differs from ISO 80000\ninline constexpr struct potential_energy final               : quantity_spec<mechanical_energy> {} potential_energy;                                                  // differs from ISO 80000\ninline constexpr struct gravitational_potential_energy final : quantity_spec<potential_energy, mass * acceleration_of_free_fall * height> {} potential_energy;        // not in ISO 80000\ninline constexpr struct elastic_potential_energy final       : quantity_spec<potential_energy, spring_constant * pow<2>(amount_of_compression)> {} potential_energy;  // not in ISO 80000\ninline constexpr struct kinetic_energy final                 : quantity_spec<mechanical_energy, mass* pow<2>(speed)> {} kinetic_energy;                               // differs from ISO 80000\ninline constexpr struct enthalpy final                       : quantity_spec<energy> {} enthalpy;                                                                     // differs from ISO 80000\ninline constexpr struct internal_energy final                : quantity_spec<enthalpy> {} internal_energy;                                                            // differs from ISO 80000\ninline constexpr auto thermodynamic_energy = internal_energy;\ninline constexpr struct Helmholtz_energy final               : quantity_spec<internal_energy> {} Helmholtz_energy;\ninline constexpr auto Helmholtz_function = Helmholtz_energy;\ninline constexpr struct Gibbs_energy final                   : quantity_spec<enthalpy> {} Gibbs_energy;\ninline constexpr auto Gibbs_function = Gibbs_energy;\n

    Again, the first parameter of quantity_spec determines the position in the tree. If a second argument is provided, it denotes a recipe for this quantity.

    With the above simple definitions we've automatically addressed our energy-related issues from the Various quantities of the same dimension and kinds chapter of the \"Part 2\" article.

    "},{"location":"blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/#modeling-a-hierarchy-of-kind-dimensionless","title":"Modeling a hierarchy of kind dimensionless","text":"

    As the last example for this article, let's try to model and implement quantities of dimension one, often also called dimensionless quantities. This quantity hierarchy contains more than one quantity kind and more than one unit in its tree:

    flowchart TD\n    dimensionless[\"<b>dimensionless</b><br>[one]\"]\n    dimensionless --- rotation[\"<b>rotation</b>\"]\n    dimensionless --- thermodynamic_efficiency[\"<b>thermodynamic_efficiency</b><br><i>(work / heat)</i>\"]\n    dimensionless --- angular_measure[\"<b>angular_measure</b><br><i>(arc_length / radius)</i><br>[rad]\"]\n    angular_measure --- rotational_displacement[\"<b>rotational_displacement</b><br><i>(path_length / radius)</i>\"]\n    angular_measure --- phase_angle[\"<b>phase_angle</b>\"]\n    dimensionless --- solid_angular_measure[\"<b>solid_angular_measure</b><br><i>(area / pow<2>(radius))</i><br>[sr]\"]\n    dimensionless --- drag_factor[\"<b>drag_factor</b><br><i>(drag_force / (mass_density * pow<2>(speed) * area))</i>\"]\n    dimensionless --- storage_capacity[\"<b>storage_capacity</b><br>[bit]\"] --- equivalent_binary_storage_capacity[\"<b>equivalent_binary_storage_capacity</b>\"]\n    dimensionless --- ...

    To enable such support in the library, we provided an is_kind specifier that can be appended to the quantity specification:

    inline constexpr struct dimensionless final            : quantity_spec<detail::derived_quantity_spec<>{}> {} dimensionless;\ninline constexpr struct rotation final                 : quantity_spec<dimensionless> {} rotation;\ninline constexpr struct thermodynamic_efficiency final : quantity_spec<dimensionless, work / heat> {} efficiency;\ninline constexpr struct angular_measure final          : quantity_spec<dimensionless, arc_length / radius, is_kind> {} angular_measure;\ninline constexpr struct rotational_displacement final  : quantity_spec<angular_measure, path_length / radius> {} rotational_displacement;\ninline constexpr struct phase_angle final              : quantity_spec<angular_measure> {} phase_angle;\ninline constexpr struct solid_angular_measure final    : quantity_spec<dimensionless, area / pow<2>(radius), is_kind> {} solid_angular_measure;\ninline constexpr struct drag_factor final              : quantity_spec<dimensionless, drag_force / (mass_density * pow<2>(speed) * area)> {} drag_factor;\ninline constexpr struct storage_capacity final         : quantity_spec<dimensionless, is_kind> {} storage_capacity;\n

    With the above, we can constrain radian, steradian, and bit to be allowed for usage with specific quantity kinds only:

    inline constexpr struct radian final    : named_unit<\"rad\", metre / metre, kind_of<isq::angular_measure>> {} radian;\ninline constexpr struct steradian final : named_unit<\"sr\", square(metre) / square(metre), kind_of<isq::solid_angular_measure>> {} steradian;\ninline constexpr struct bit final       : named_unit<\"bit\", one, kind_of<storage_capacity>> {} bit;\n

    but still allow the usage of one and its scaled versions for such quantities.

    Note

    dimensionless is a special quantity which serves as an identity element in quantity equations. It is predefined in the library's framework and there is no way for the user to define it or something similar to it.

    "},{"location":"blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/#to-be-continued","title":"To be continued...","text":"

    In the next part of this series, we will present how our ISQ model helps to address the remaining issues described in the Part 2 of our series.

    "},{"location":"blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/","title":"International System of Quantities (ISQ): Part 5 - Benefits","text":"

    In the previous articles, we introduced the International System of Quantities, described how we can model and implement it in a programming language, and presented the issues of software that does not use such abstraction to implement a units library.

    Some of the issues raised in Part 2 of our series were addressed in Part 3 already. This article will present how our ISQ model elegantly addresses the remaining problems.

    "},{"location":"blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/#articles-from-this-series","title":"Articles from this series","text":""},{"location":"blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/#generic-but-safe-interfaces","title":"Generic but safe interfaces","text":"

    Let's start with the implementation of a generic utility function that would calculate the average speed based on provided arguments. The resulting quantity should use a derived unit of the provided arguments (e.g., km/h for km and h, m/s for m and s, ...).

    With C++ concepts backed up with ISQ quantities, we can simply type it as:

    constexpr QuantityOf<isq::speed> auto avg_speed(QuantityOf<isq::length> auto d,\n                                                QuantityOf<isq::time> auto t)\n{\n  return d / t;\n}\n

    The above constrains the algorithm to proper quantity types and ensures that a quantity of speed is returned. The latter is essential not only for the users to better understand what the function does but also serves as a unit test for our implementation. It ensures that our quantity equations are correct in the implementation part of the function, and we indeed return a quantity of speed.

    "},{"location":"blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/#non-convertible-units-of-currency","title":"Non-convertible units of currency","text":"

    Our second example was about disjoint units of currency. We want to use various units of currency but we can't provide compile-time known conversion factors between those as such ratios are only known at runtime.

    First, we define:

    inline constexpr struct dim_currency final : base_dimension<\"$\"> {} dim_currency;\ninline constexpr struct currency final : quantity_spec<dim_currency> {} currency;\n\ninline constexpr struct euro final : named_unit<\"EUR\", kind_of<currency>> {} euro;\ninline constexpr struct us_dollar final : named_unit<\"USD\", kind_of<currency>> {} us_dollar;\n\nnamespace unit_symbols {\n\ninline constexpr auto EUR = euro;\ninline constexpr auto USD = us_dollar;\n\n}\n\nstatic_assert(!std::equality_comparable_with<quantity<euro, int>, quantity<us_dollar, int>>);\n

    Next, we can provide a custom currency exchange facility that accounts for a specific point in time:

    template<Unit auto From, Unit auto To>\n[[nodiscard]] double exchange_rate(std::chrono::sys_seconds timestamp)\n{\n  // user-provided logic...\n}\n\ntemplate<UnitOf<currency> auto To, QuantityOf<currency> From>\nQuantityOf<currency> auto exchange_to(From q, std::chrono::sys_seconds timestamp)\n{\n  const auto rate =\n    static_cast<From::rep>(exchange_rate<From::unit, To>(timestamp) * q.numerical_value_in(q.unit));\n  return rate * From::quantity_spec[To];\n}\n

    Finally, we can use our simple model in the following way:

    using namespace unit_symbols;\nusing namespace std::chrono;\n\nconst auto yesterday = time_point_cast<seconds>(system_clock::now() - hours{24});\nconst quantity price_usd = 100 * USD;\nconst quantity price_euro = exchange_to<euro>(price_usd, yesterday);\n\nstd::cout << price_usd << \" -> \" << price_euro << \"\\n\";\n// std::cout << price_usd + price_euro << \"\\n\";  // does not compile\n

    Note

    It would be better to model the above prices as quantity points, but this is a subject for a different article .

    "},{"location":"blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/#derived-quantities-of-the-same-dimension-but-different-kinds","title":"Derived quantities of the same dimension but different kinds","text":"

    Until now, the issues discussed have not actually required modeling of the ISQ. The introduction of physical dimensions would be enough, and indeed, this is what most of the libraries on the market do. However, we have more exciting challenges to solve as well.

    The next issue was related to different quantities having the same dimension. In many cases, we want to prevent conversions and any other compatibility between such distinct quantities.

    Let's try to implement our fuel consumption example. First, we define the quantity type and a handy identifier for a derived unit that we want to use:

    inline constexpr struct fuel_consumption final : quantity_spec<isq::volume / isq::length> {} fuel_consumption;\ninline constexpr auto L_per_100km = si::litre / (mag<100> * si::kilo<si::metre>);\n\nstatic_assert(fuel_consumption != isq::area);\nstatic_assert(fuel_consumption.dimension == isq::area.dimension);\n

    Next, we define two quantities. The first one is based only on a derived unit of L/[100 km], while the second uses a strongly typed quantity type:

    quantity q1 = 5.8 * L_per_100km;\nquantity q2 = fuel_consumption(6.7 * L_per_100km);\nstd::println(\"Fuel consumptions: {}, {}\", q1, q2);\n\nstatic_assert(implicitly_convertible(q1.quantity_spec, isq::area));\nstatic_assert(!implicitly_convertible(q2.quantity_spec, isq::area));\nstatic_assert(!explicitly_convertible(q2.quantity_spec, isq::area));\nstatic_assert(!castable(q2.quantity_spec, isq::area));\n

    As we can see, with just units (especially derived ones) and dimensions, we often can't achieve the same level of safety as with adequately modeled hierarchies of quantities. Only in case of q2 we can prevent incorrect conversions to a different quantity of the same dimension.

    "},{"location":"blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/#various-quantities-of-the-same-dimension-and-kinds","title":"Various quantities of the same dimension and kinds","text":"

    In the previous example, area and fuel consumption were quantities of the same dimension but of different kinds. In engineering, there are also many cases where we need to model distinct quantities of the same kind.

    Let's try to improve the safety of our Box example.

    First, we need to extend our ISQ definitions by the horizontal length quantity and a horizontal area derived from it:

    inline constexpr struct horizontal_length final : quantity_spec<isq::length> {} horizontal_length;\ninline constexpr struct horizontal_area final : quantity_spec<isq::area, horizontal_length * isq::width> {} horizontal_area;\n

    Note

    isq::length denotes any quantity of length (not only the horizontal one).

    static_assert(implicitly_convertible(horizontal_length, isq::length));\nstatic_assert(!implicitly_convertible(isq::length, horizontal_length));\n\nstatic_assert(implicitly_convertible(horizontal_area, isq::area));\nstatic_assert(!implicitly_convertible(isq::area, horizontal_area));\n\nstatic_assert(implicitly_convertible(isq::length * isq::length, isq::area));\nstatic_assert(!implicitly_convertible(isq::length * isq::length, horizontal_area));\n\nstatic_assert(implicitly_convertible(horizontal_length * isq::width, isq::area));\nstatic_assert(implicitly_convertible(horizontal_length * isq::width, horizontal_area));\n

    With simple two lines of definition, we made the above logic automatically work without needing additional customization for special cases. Based on hierarchies of derived quantities and their recipes, the proposed model automatically inherits the properties of base quantities involved in the recipe. This makes the composition of derived quantities very easy, which is not true for alternative solutions based on tag types that do not compose their properties.

    Now we can refactor our Box to benefit from the introduced safe abstractions:

    class Box {\n  quantity<horizontal_length[m]> length_;\n  quantity<isq::width[m]> width_;\n  quantity<isq::height[m]> height_;\npublic:\n  Box(quantity<horizontal_length[m]> l, quantity<isq::width[m]> w, quantity<isq::height[m]> h):\n    length_(l), width_(w), height_(h)\n  {}\n\n  quantity<horizontal_area[m2]> floor() const { return length_ * width_; }\n  // ...\n};\n

    It is important to note that the safety can be enforced only when a user provides typed quantities as arguments to the functions:

    Box my_box1(2 * m, 3 * m, 1 * m);\nBox my_box2(2 * horizontal_length[m], 3 * isq::width[m], 1 * isq::height[m]);\nBox my_box3(horizontal_length(2 * m), isq::width(3 * m), isq::height(1 * m));\n

    Important

    It is up to the user to decide when and where to care about explicit quantity types and when to prefer simple unit-only mode.

    "},{"location":"blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/#various-kinds-of-dimensionless-quantities","title":"Various kinds of dimensionless quantities","text":"

    Most of the quantities hierarchies describe only one kind. There are some exceptions, though. One of them is a hierarchy of dimensionless quantities. This tree defines quantities that denote:

    Each of the above could form a separate tree of mutually comparable quantities. However, all of them have a common property. Every quantity from this tree, despite often being measured in a dedicated unit (e.g., bit, rad, sr), should also be able to be measured in a unit one.

    We've seen how to model such a hierarchy in a previous article in our series. This time, we will see a simplified part of a concrete, real-life example for this use case.

    We often need to provide strong types for different counts in the digital signal processing domain. Abstractions like samples, beats, MIDI clock, and others should not be possible to be intermixed with each other:

    namespace ni {\n\ninline constexpr struct SampleCount final : quantity_spec<dimensionless, is_kind> {} SampleCount;\ninline constexpr struct UnitSampleAmount final : quantity_spec<dimensionless, is_kind> {} UnitSampleAmount;\ninline constexpr struct MIDIClock final : quantity_spec<dimensionless, is_kind> {} MIDIClock;\ninline constexpr struct BeatCount final : quantity_spec<dimensionless, is_kind> {} BeatCount;\n

    We should also be able to create derived quantities from those. For example, when we divide such a quantity by time we should get a new strong quantity that can be measured in both a dedicated unit (e.g., Smpl/s for sample rate) and hertz:

    inline constexpr struct SampleDuration final : quantity_spec<isq::period_duration> {} SampleDuration;\ninline constexpr struct SamplingRate final : quantity_spec<isq::frequency, SampleCount / SampleDuration> {} SamplingRate;\n\ninline constexpr auto Amplitude = UnitSampleAmount;\ninline constexpr auto Level = UnitSampleAmount;\ninline constexpr struct Power final : quantity_spec<Level * Level> {} Power;\n\ninline constexpr struct BeatDuration final : quantity_spec<isq::period_duration> {} BeatDuration;\ninline constexpr struct Tempo final : quantity_spec<isq::frequency, BeatCount / BeatDuration> {} Tempo;\n

    We can also define a collection of units associated with specific quantity kinds and their symbols:

    inline constexpr struct Sample final : named_unit<\"Smpl\", one, kind_of<SampleCount>> {} Sample;\ninline constexpr struct SampleValue final : named_unit<\"PCM\", one, kind_of<UnitSampleAmount>> {} SampleValue;\ninline constexpr struct MIDIPulse final : named_unit<\"p\", one, kind_of<MIDIClock>> {} MIDIPulse;\n\ninline constexpr struct QuarterNote final : named_unit<\"q\", one, kind_of<BeatCount>> {} QuarterNote;\ninline constexpr struct HalfNote final : named_unit<\"h\", mag<2> * QuarterNote> {} HalfNote;\ninline constexpr struct DottedHalfNote final : named_unit<\"h.\", mag<3> * QuarterNote> {} DottedHalfNote;\ninline constexpr struct WholeNote final : named_unit<\"w\", mag<4> * QuarterNote> {} WholeNote;\ninline constexpr struct EightNote final : named_unit<\"8th\", mag_ratio<1, 2> * QuarterNote> {} EightNote;\ninline constexpr struct DottedQuarterNote final : named_unit<\"q.\", mag<3> * EightNote> {} DottedQuarterNote;\ninline constexpr struct QuarterNoteTriplet final : named_unit<\"qt\", mag_ratio<1, 3> * HalfNote> {} QuarterNoteTriplet;\ninline constexpr struct SixteenthNote final : named_unit<\"16th\", mag_ratio<1, 2> * EightNote> {} SixteenthNote;\ninline constexpr struct DottedEightNote final : named_unit<\"q.\", mag<3> * SixteenthNote> {} DottedEightNote;\n\ninline constexpr auto Beat = QuarterNote;\n\ninline constexpr struct BeatsPerMinute final : named_unit<\"bpm\", Beat / si::minute> {} BeatsPerMinute;\ninline constexpr struct MIDIPulsePerQuarter final : named_unit<\"ppqn\", MIDIPulse / QuarterNote> {} MIDIPulsePerQuarter;\n\nnamespace unit_symbols {\n\ninline constexpr auto Smpl = Sample;\ninline constexpr auto pcm = SampleValue;\ninline constexpr auto p = MIDIPulse;\n\ninline constexpr auto n_wd = 3 * HalfNote;\ninline constexpr auto n_w = WholeNote;\ninline constexpr auto n_hd = DottedHalfNote;\ninline constexpr auto n_h = HalfNote;\ninline constexpr auto n_qd = DottedQuarterNote;\ninline constexpr auto n_q = QuarterNote;\ninline constexpr auto n_qt = QuarterNoteTriplet;\ninline constexpr auto n_8thd = DottedEightNote;\ninline constexpr auto n_8th = EightNote;\ninline constexpr auto n_16th = SixteenthNote;\n\n}\n\n}  // namespace ni\n

    With the above, we can safely work with each quantity and use SI or domain-specific units as needed:

    using namespace ni::unit_symbols;\nusing namespace mp_units::si::unit_symbols;\n\nconst auto sr1 = ni::GetSampleRate();\nconst auto sr2 = 48'000.f * Smpl / s;\n\nconst auto samples = 512 * Smpl;\n\nconst auto sampleTime1 = (samples / sr1).in(s);\nconst auto sampleTime2 = (samples / sr2).in(ms);\n\nconst auto sampleDuration1 = (1 / sr1).in(ms);\nconst auto sampleDuration2 = (1 / sr2).in(ms);\n\nconst auto rampTime = 35.f * ms;\nconst auto rampSamples1 = (rampTime * sr1).force_in<int>(Smpl);\nconst auto rampSamples2 = (rampTime * sr2).force_in<int>(Smpl);\n\nstd::println(\"Sample rate 1 is: {}\", sr1);\nstd::println(\"Sample rate 2 is: {}\", sr2);\n\nstd::println(\"{} @ {} is {::N[.5f]}\", samples, sr1, sampleTime1);\nstd::println(\"{} @ {} is {::N[.5f]}\", samples, sr2, sampleTime2);\n\nstd::println(\"One sample @ {} is {::N[.5f]}\", sr1, sampleDuration1);\nstd::println(\"One sample @ {} is {::N[.5f]}\", sr2, sampleDuration2);\n\nstd::println(\"{} is {} @ {}\", rampTime, rampSamples1, sr1);\nstd::println(\"{} is {} @ {}\", rampTime, rampSamples2, sr2);\n

    The above prints:

    Sample rate 1 is: 44100 Hz\nSample rate 2 is: 48000 Smpl/s\n512 Smpl @ 44100 Hz is 0.01161 s\n512 Smpl @ 48000 Smpl/s is 10.66667 ms\nOne sample @ 44100 Hz is 0.02268 ms\nOne sample @ 48000 Smpl/s is 0.02083 ms\n35 ms is 1543 Smpl @ 44100 Hz\n35 ms is 1680 Smpl @ 48000 Smpl/s\n

    We can also do a bit more advanced computations to get the following:

    auto sampleValue = -0.4f * pcm;\nauto power1 = sampleValue * sampleValue;\nauto power2 = -0.2 * pow<2>(pcm);\n\nauto tempo = ni::GetTempo();\nauto reverbBeats = 1 * n_qd;\nauto reverbTime = reverbBeats / tempo;\n\nauto pulsePerQuarter = value_cast<float>(ni::GetPPQN());\nauto transportPosition = ni::GetTransportPos();\nauto transportBeats = (transportPosition / pulsePerQuarter).in(n_q);\nauto transportTime = (transportBeats / tempo).in(s);\n\nstd::println(\"SampleValue is: {}\", sampleValue);\nstd::println(\"Power 1 is: {}\", power1);\nstd::println(\"Power 2 is: {}\", power2);\n\nstd::println(\"Tempo is: {}\", tempo);\nstd::println(\"Reverb Beats is: {}\", reverbBeats);\nstd::println(\"Reverb Time is: {}\", reverbTime.in(s));\nstd::println(\"Pulse Per Quarter is: {}\", pulsePerQuarter);\nstd::println(\"Transport Position is: {}\", transportPosition);\nstd::println(\"Transport Beats is: {}\", transportBeats);\nstd::println(\"Transport Time is: {}\", transportTime);\n

    which prints:

    SampleValue is: -0.4 PCM\nPower 1 is: 0.16000001 PCM\u00b2\nPower 2 is: -0.2 PCM\u00b2\nTempo is: 110 bpm\nReverb Beats is: 1 q.\nReverb Time is: 0.8181818 s\nPulse Per Quarter is: 960 ppqn\nTransport Position is: 15836 p\nTransport Beats is: 16.495832 q\nTransport Time is: 8.997726 s\n

    Info

    More about this example can be found in \"Exploration of Strongly-typed Units in C++: A Case Study from Digital Audio\" CppCon 2023 talk by Roth Michaels.

    "},{"location":"blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/#to-be-continued","title":"To be continued...","text":"

    In the next part of this series, we will discuss the challenges and issues related to the modeling of the ISQ with a programming language.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/","title":"International System of Quantities (ISQ): Part 6 - Challenges","text":"

    This article might be the last one from our series. This time, we will discuss the challenges and issues with modeling of the ISQ in software.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#articles-from-this-series","title":"Articles from this series","text":""},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#ambiguity","title":"Ambiguity","text":"

    Some quantity names are ambiguous. It is not a problem of ISQ but of the English language and the way we communicate things. When I say: \"Every width is a length, but not every length is a width\" most people understand this right away. However, the same people trying to model our 3D box problem try to do it as follows:

    class Box {\n  quantity<isq::length[m]> length_;\n  quantity<isq::width[m]> width_;\n  quantity<isq::height[m]> height_;\npublic:\n  // ...\n};\n

    This looks correct at first sight. Only when we think about the sentence mentioned above will we realize that this implementation has a problem. We intended to specify three orthogonal dimensions of the box, each of which will be a strong quantity that is not convertible to others. But we've failed.

    When we look at the tree of quantities of length we immediately see that both width and height are special lengths so they are convertible to it.

    To implement our task correctly, we had to define and use a new quantity of kind length:

    inline constexpr struct horizontal_length final : quantity_spec<isq::length> {} horizontal_length;\n

    We do not propose adding horizontal length to ISO 80000-3. There are probably other similar cases as well, but so far, this was the most common and obvious one we've encountered.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#no-common-quantities","title":"No common quantities","text":"

    ISO 80000-1:2009 explicitly states:

    Quote

    Two or more quantities cannot be added or subtracted unless they belong to the same category of mutually comparable quantities.

    This means that we should be able to add and subtract any quantities as long as they belong to the same kind. However, ISO/IEC documents do not provide any rules or even hints about what should be the result of such operations.

    If it is possible to add radius and distance, then what quantity should be provided in return? Undoubtedly, the resulting quantity type can't be the same as any of the arguments. It is not a radius or distance. It is some closer unspecified length, though.

    Info

    Finding the correct solution took us many months of experimentation and implementation. Based on the hierarchy tree of quantities, we can define conversion rules and what a common quantity should be.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#lack-of-consistency","title":"Lack of consistency","text":"

    The documents of ISO/IEC 80000 are not 100% consistent, and programming languages do not like inconsistencies.

    For example:

    To be consistent, ISO/IEC should either:

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#lack-of-definitions","title":"Lack of definitions","text":"

    ISQ defines derived quantities in terms of other quantities provided in the series. However, some definitions mention quantities that are not defined in the ISQ at all.

    For example, weight is defined as \\(F_\\textsf{g} = m\\;g\\), where \\(m\\) is the mass of the body (item 4-1 of ISO 80000-4 \"Mechanics\"), and \\(g\\) is the local acceleration of free fall (ISO 80000-3).

    The problem here is that ISO 80000-3 never defines a quantity with a symbol \\(g\\) or named as a local acceleration of free fall. The closest one we have is acceleration (item 3-11) with a symbol \\(a\\).

    Info

    To have a proper definition of weight in mp-units that is not defined in terms of just any kind of acceleration, we have added isq::acceleration_of_free_fall in our definitions as an extension to the original ISQ set of quantities.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#not-engineering-friendly","title":"Not engineering-friendly","text":"

    Many quantities have proper physical definitions, but they are sometimes not engineering-friendly.

    For example, velocity is defined as a rate of change of position vector \\(v = \\frac{\\textsf{d}r}{\\textsf{d}t}\\), where \\(r\\) denotes the position vector (item 3\u20111.10) and \\(t\\) the duration (item 3\u20119).

    Next, a speed quantity is defined as the magnitude of velocity. Despite being physically correct, requiring every speed to be derived from the vector quantity of velocity in software would be inconvenient. If this was the only case, people would always need to use vector representations of position vectors to talk about speeds, which differs from what we do in practice. In practice, we divide any kind of length by time to get some kind of speed.

    ISO 80000-3 provides length, height, distance and other quantities of kind length that when divided by duration can serve really well to calculate speed.

    Info

    This is why in mp-units, we decided to divert from the official definition of speed and define it as:

    inline constexpr struct speed : quantity_spec<speed, length / time> {} speed;\n

    This allows us to create a quantity of kind speed from any quantity of length divided by time.

    Additionally, it is essential to note that for the needs of our library, defining velocity as position_vector / duration would be wrong. We miss the delta part here. Even though it is not mentioned in ISO 80000-3, the delta of position vectors is actually a displacement. This is why our velocity is defined as:

    inline constexpr struct velocity : quantity_spec<speed, displacement / duration> {} velocity;\n

    Please also note that velocity is defined as a more specialized quantity of speed.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#affine-space-agnostic","title":"Affine space agnostic","text":"

    The affine space is a powerful abstraction, allowing us to model some problems safer or more accurately. It has two types of entities:

    Vectors support all the arithmetics operations, but points have some limitations. It is not possible to:

    ISO/IEC series does not acknowledge this abstraction even though it would be really useful in some cases. Let's discuss the following two examples.

    What does it mean to add two altitudes? It is not meaningful. On the other hand, subtracting those should not result in an altitude, but in a quantity of height. Adding or subtracting height to/from altitude results in altitude. Subtracting altitude from height is meaningless again. Those quantities clearly model affine space. Maybe this is why ISQ defines them as one quantity type height/depth/altitude?

    What does it mean to add two position vectors? It is not meaningful again. However, subtracting those results in a displacement as we noted in the previous chapter. Adding or subtracting displacement to/from position vector results in another position vector, and subtracting position vector from displacement does not have physical sense. Again, those quantities perfectly model affine space. However, this time, those are defined as separate and independent quantities (i.e., displacement is not modeled as delta position vector or position vector is not modeled as a displacement from the origin of a coordinate system).

    Info

    Currently, mp-units does not enforce the affine space behavior for such quantities. Today, subtracting two altitudes result in an altitude and subtracting two position vectors result in a position vector. However, we plan to support automatic conversion to a proper quantity type on subtraction and addition shortly.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#non-negative-quantities","title":"Non-negative quantities","text":"

    Some quantities in the ISQ are defined as non-negative. This is a really interesting property that may be checked at runtime to increase safety. However, the number of such quantities is minimal. From a few hundred quantities provided by the ISO/IEC series, only the following have this property mentioned explicitly:

    If height was defined separately from altitude, it could probably also join this group.

    Let's think a bit more about this. What does it mean that a quantity is non-negative? Indeed, it is hard to imagine something of a negative width or radius. However, if we subtract two widths, the second one may be larger. This will result in a negative quantity of width, violating our precondition. So, is it non-negative or not?

    Again, we have to talk about the affine space abstractions. Every empirical measurement can be expressed as a point. Such points for some quantities may be non-negative indeed.

    Non-negative quantities do not end on the ones provided above. For example, speed is a good example here as well. In general, all magnitudes of vector quantities will also have this property.

    When subtracting two points, we end up with a delta/displacement type, which may be negative even for quantities listed as non-negative in the ISQ. As stated in the previous chapter, having affine space abstractions acknowledged in ISQ would greatly help here.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#lack-of-quantity-recipes","title":"Lack of quantity recipes","text":"

    Definition of many derived quantities provides their recipes in the form of quantity equations (e.g., weight equation in the previous chapter). However, some of them do not. Instead, they often provide a very generic description.

    For example, force is defined as:

    Quote

    vector (ISO 80000-2) quantity describing interaction between bodies or particles.

    This is not helpful for programming languages that like explicit definitions. Different vendors may interpret the above differently, which will result in different implementations that will not be compatible with each other.

    As the derived quantity of force has to be a vector quantity, it has to be defined in terms of at least one other vector quantity. We have a few to choose from:

    It is not stated explicitly in ISQ which one of those should be used and how.

    Info

    In mp-units we decided to define force as \\(F = m\\;a\\).

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#lack-of-generic-quantities-and-name-conflicts","title":"Lack of generic quantities and name conflicts","text":"

    In the previous chapter, we complained about some definitions needing to be more complex or generic. On the other hand, we also lack some generic quantities in ISQ that could serve as a root for a quantity hierarchy tree.

    For example:

    First, the above definitions have somehow conflicting names which makes it hard for the programming languages to name them consistently by different vendors.

    Info

    In mp-units, we chose mechanical_power and electromagnetism_power for those.

    Second, we do not have any other more generic definition of power to put above those in the tree. Not having it makes it hard to answer what should be the result of:

    quantity q = isq::mechanical_power(42 * W) + isq::electromagnetism_power(60 * W);\n

    Info

    To solve the above problem, we have added isq::power in mp-units, that has a really generic definition of:

    inline constexpr struct power : quantity_spec<mass* pow<2>(length) / pow<3>(time)> {} power;\n
    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#invalid-definitions-order","title":"Invalid definitions order","text":"

    Energy is defined a bit better than power, but still not without issues.

    The first time ISQ mentions energy is in the ISO 80000-4 \"Mechanics\". It defines potential energy, kinetic energy, and a mechanical energy as the sum of the first two. Right after that a mechanical work/work is defined.

    Then ISO 80000-5 \"Thermodynamics\" defines energy <thermodynamics> as:

    Quote

    ability of a system to do work (ISO 80000-4).

    Next, internal energy/thermodynamic energy is defined in terms of the change of heat.

    From the above, it seems that what is called energy <thermodynamics> should actually be the root of our tree and probably be provided in Part 4 before the mechanical energy is defined.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#hierarchies-of-derived-quantities","title":"Hierarchies of derived quantities","text":"

    Derived quantities of the same kind are often independently defined in the ISQ. The ISO/IEC 80000 series often does not suggest any hierarchy between those. Even more, it states:

    ISO/IEC Guide 99

    The division of \u2018quantity\u2019 according to \u2018kind of quantity\u2019 is, to some extent, arbitrary.

    Because of this, it is unknown or ambiguous how to form a hierarchy tree for such quantities.

    To get some sense of the complexity here, let's look again at our tree of quantities of a kind energy:

    flowchart TD\n    energy[\"<b>energy</b><br><i>(mass * length<sup>2</sup> / time<sup>2</sup>)</i><br>[J]\"]\n    energy --- mechanical_energy[\"<b>mechanical_energy</b>\"]\n    mechanical_energy --- potential_energy[\"<b>potential_energy</b>\"]\n    mechanical_energy --- kinetic_energy[\"<b>kinetic_energy</b>\"]\n    energy --- enthalpy[\"<b>enthalpy</b>\"]\n    enthalpy --- internal_energy[\"<b>internal_energy</b> / <b>thermodynamic_energy</b>\"]\n    internal_energy --- Helmholtz_energy[\"<b>Helmholtz_energy</b> / <b>Helmholtz_function</b>\"]\n    enthalpy --- Gibbs_energy[\"<b>Gibbs_energy</b> / <b>Gibbs_function</b>\"]\n    energy --- active_energy[\"<b>active_energy</b>\"]

    Not being exact means that every vendor may implement it differently. This will result in:

    It would be great if ISQ could provide specific division of quantities into kinds and more information about the position of each quantity within the hierarchy of quantities of the same kind.

    Important

    We can try to do this by ourselves, but it is tough. Probably no one, for sure we are not, is an expert in all the fields of ISO/IEC 80000 applicability.

    We need the help of subject matter experts who will help us build those trees for their domains and then verify that everything works as expected.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#the-same-or-a-different-kind","title":"The same or a different kind?","text":"

    Some quantities are more complicated than others. For example, power has:

    How should we model this? Maybe those should be two or three independent trees of quantities, each having its own unit?

    flowchart TD\n    power[\"<b>power</b><br><i>(mass * length<sup>2</sup> / time<sup>3</sup>)</i><br>[W]\"]\n    power --- mechanical_power[\"<b>mechanical_power</b><br><i>(scalar_product(force, velocity))</i>\"]\n    power --- electromagnetism_power[\"<b>electromagnetism_power</b> | <b>instantaneous_power</b><br><i>(instantaneous_voltage * instantaneous_electric_current)</i>\"]\n    power --- active_power[\"<b>active_power</b><br><i>(1 / period * instantaneous_power * time)<br>(re(complex_power))</i>\"]\n\n    nonactive_power[\"<b>nonactive_power</b><br><i>(mass * length<sup>2</sup> / time<sup>3</sup>)</i><br>[VA]\"]\n    nonactive_power --- reactive_power[\"<b>reactive_power</b><br><i>(im(complex_power))</i><br>[var]\"]\n\n    complex_power[\"<b>complex_power</b><br>{complex}<br><i>(voltage_phasor * electric_current_phasor)<br>(active_power + j * reactive_power)</i><br>[VA]\"]\n    complex_power --- apparent_power[\"<b>apparent_power</b><br><i>(voltage * electric_current)<br>(mod(complex_power))</i>\"]

    This will mean that we will not be able to add or compare active power, reactive power, and apparent power, which probably makes a lot of sense. However, it also means that the following will fail to compile:

    quantity apparent = isq::apparent_power(100 * VA);\nquantity active = isq::active_power(60 * W);\nquantity<isq::nonactive_power[VA]> q = sqrt(pow<2>(apparent) - pow<2>(active)); // Compile-time error\n

    Also the following will not work:

    quantity active = isq::active_power(60 * W);\nquantity reactive = isq::reactive_power(40 * var);\nquantity<isq::apparent_power[VA]> q = sqrt(pow<2>(active) + pow<2>(reactive)); // Compile-time error\n

    If we want the above to work maybe we need to implement the tree as follows?

    flowchart TD\n    power[\"<b>power</b><br><i>(mass * length<sup>2</sup> / time<sup>3</sup>)</i><br>[W]\"]\n    power --- mechanical_power[\"<b>mechanical_power</b><br><i>(scalar_product(force, velocity))</i>\"]\n    power --- electromagnetism_power[\"<b>electromagnetism_power</b> | <b>instantaneous_power</b><br><i>(instantaneous_voltage * instantaneous_electric_current)</i>\"]\n    power --- apparent_power[\"<b>apparent_power</b><br><i>(voltage * electric_current)<br>(mod(complex_power))</i><br>[VA]\"]\n    apparent_power --- active_power[\"<b>active_power</b><br><i>(1 / period * instantaneous_power * time)<br>(re(complex_power))</i>\"]\n    apparent_power --- nonactive_power[\"<b>nonactive_power</b><br><i>(sqrt(apparent_power<sup>2</sup> - active_power<sup>2</sup>))</i><br>\"]\n    nonactive_power --- reactive_power[\"<b>reactive_power</b><br><i>(im(complex_power))</i><br>[var]\"]\n    apparent_power --- complex_power[\"<b>complex_power</b><br>{complex}<br><i>(voltage_phasor * electric_current_phasor)<br>(active_power + j * reactive_power)</i>\"]

    However, the above allows direct addition and comparison of active power and nonactive power, and also will not complain if someone will try to use watt (W) as a unit of apparent power or reactive power.

    Again, ISQ does not provide a direct answer here.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#more-base-quantities","title":"More base quantities?","text":"

    Is ISQ really based on only seven base quantities? Let's look at the definition of traffic intensity in IEC 80000-13 \"Information science and technology\":

    Quote

    number of simultaneously busy resources in a particular pool of resources.

    It looks like a definition of a specialized dimensionless quantity or, more correctly, a quantity of dimension one. This would not be the only such case. Even in the same Part 13, we can find quantities like storage capacity with a similar property.

    Only when we look closer do we start to see differences. All dimensionless quantities, even if they have their own dedicated units, can also be measured in a unit of one (1). This is true for storage capacity (also measured in bits), angular measure (also measured in radians), _solid angular measure (also measured in steradians), and more.

    However, traffic intensity can only be measured in erlangs (E), not in a unit one (1). Does it mean that it is a \"hidden\" 8-th base quantity in ISQ? If so, should it have its own dimension as well?

    Angular quantities are another interesting case here. Scientists have written petitions and papers for years to make them an additional dimension in ISQ and SI. More about this can be found in our documentation's Strong Angular System chapter.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#summary","title":"Summary","text":"

    ISQ is tremendous and solves many problems we had in modeling various subjects for years in software. As a result, we have more powerful tools in our hands that allow us to deliver safer products.

    Unfortunately, ISQ, contrarily to SI, is not widely recognized, and no libraries besides mp-units model it in any programming language. Keeping it behind a paywall does not help either. We hope that posts from this series will spread in the community, raise awareness of ISQ and its benefits, and encourage authors of other libraries to implement it in their products.

    Despite all the benefits, it is essential to realize that ISQ has many problems. International standards should be specified in such a way that there is no room for ambiguity in their interpretation by different parties trying to use them. As described above, this is not the case here.

    ISQ is not ready to be unambiguously modeled in software by various vendors. Here are the most important problems to solve to allow this:

    1. ISQ needs to define basic operations on quantities:

    - what the result of addition and subtraction should be when arguments differ, \u00a0 \u00a0 - convertibility rules.

    1. The exact quantity equation recipe needs to be included for many derived quantities.
    2. Many ISQ quantities do not provide their exact relation versus other quantities of the same kind (no strict hierarchy).
    3. Some missing quantities need to be included. Others would benefit from corrected names.

    Additionally:

    could improve the safety of our programs and products that people depend on with their lives on a daily basis.

    I hope you enjoyed following this series and learned more about the International System of Quantities. Please try it out in your domain and share feedback with us. We always love to hear about the projects in which our library is being used and about use cases it helps address.

    "},{"location":"blog/2023/11/12/report-from-the-kona-2023-iso-c-committee-meeting/","title":"Report from the Kona 2023 ISO C++ Committee meeting","text":"

    Several groups in the ISO C++ Committee reviewed the P1935: A C++ Approach to Physical Units proposal in Belfast 2019 and Prague 2020. All those groups expressed interest in the potential standardization of such a library and encouraged further work. The authors also got valuable initial feedback that highly influenced the design of the V2 version of the mp-units library.

    In the following years, we scoped on getting more feedback from the production and design. This resulted in version 2 of the mp-units library that resolved many issues the users and Committee members raised. The features and interfaces of this version are close to being the best we can get with the current version of the C++ language standard.

    We submitted three new proposals related to the standardization of the quantities and units library for the last ISO C++ Committee meeting:

    Those were reviewed and briefly discussed in several groups: Numerics (SG6), Safety & Security (SG23), and Library Evolution Working Group (LEWG). Most of the feedback was positive, and the Committee is interested in spending more time on such proposals.

    The following poll was taken by the LEWG:

    LEWG POLL: Given that our time is limited, more time should be promised for a quantities and units library

    Strongly in Favor In favor Neutral Against Strongly Against 10 13 4 0 0

    Attendance: 22 + 6

    Number of Authors: 4

    Authors\u2019 position: 4x SF

    Outcome: Strong consensus in favor

    Additionally, some concerns were raised about the large scope of the proposal. We were encouraged to return with more details and design rationale in a unified paper. This is what we are working on now for the next Committee meeting that will happen in mid-March 2024 in Tokyo.

    "},{"location":"blog/2024/07/02/report-from-the-st-louis-2024-iso-c-committee-meeting/","title":"Report from the St. Louis 2024 ISO C++ Committee meeting","text":"

    We made significant progress in the standardization of this library during the ISO C++ Committee meeting in St. Louis.

    "},{"location":"blog/2024/07/02/report-from-the-st-louis-2024-iso-c-committee-meeting/#p30942r3-stdbasic_fixed_string","title":"P30942R3: std::basic_fixed_string","text":"

    First, the fixed_string was unanimously forwarded from the SG18 LEWG Incubator to the Library Evolution Working Group (LEWG). The group suggested a few minor changes to the paper, which resulted in the R3 version of the proposal.

    The paper is in excellent shape, and the entire wording is ready as well. Hopefully it will progress quickly through the remaining groups in the Committee.

    "},{"location":"blog/2024/07/02/report-from-the-st-louis-2024-iso-c-committee-meeting/#p3045r1-quantities-and-units-library","title":"P3045R1: Quantities and units library","text":"

    In the SG6 (Numerics), we had a really efficient discussion about the recently raised usability issues with temperatures and the Minimal Viable Product (MVP) scope.

    The following polls were taken:

    POLL: If WG21 adds anything to the standard to provide units or quantities, then such a solution must at least include the necessary abstractions for units, dimensions, and quantity kinds. (It does not have to provide system definitions, e.g. ISQ/SI definitions.)

    Strongly in Favor In favor Neutral Against Strongly Against 7 4 7 0 0

    POLL: If WG21 adds anything to the standard to provide units or quantities, then such a solution must at least include the necessary abstractions for units, dimensions, quantity kinds, and quantities of the same kind. (It does not have to provide system definitions, e.g. ISQ/SI definitions.)

    Strongly in Favor In favor Neutral Against Strongly Against 5 2 5 2 0

    POLL: If WG21 adds anything to the standard to provide units or quantities, then such a solution must at least include the necessary abstractions for units, dimensions, quantity kinds, and affine spaces. (It does not have to provide system definitions, e.g. ISQ/SI definitions.)

    Strongly in Favor In favor Neutral Against Strongly Against 5 0 8 1 0

    As we can see, there are no controversies about the first poll that states that the MVP should include at least:

    The next polls add either:

    SG6 considered those less important, but no one was strongly against including those in the MVP. We were asked to return with better motivation and usage examples for those features.

    If you are depending on quantities of the same kind or quantity points in your project and you would like to see them in the std library, please let us know about your use cases.

    Besides SG6, we spent six hours in the SG18 LEWG Incubator discussing the details of the library design. The proposal was very well received, and we got a few valuable comments and suggestions that we will apply to the next version of the paper.

    "},{"location":"blog/2024/04/15/report-from-the-tokyo-2024-iso-c-committee-meeting/","title":"Report from the Tokyo 2024 ISO C++ Committee meeting","text":"

    The Tokyo 2024 meeting was a very important step in the standardization of this library. Several WG21 groups reviewed proposals, and the feedback was really good.

    "},{"location":"blog/2024/04/15/report-from-the-tokyo-2024-iso-c-committee-meeting/#p3045r0-quantities-and-units-library","title":"P3045R0: Quantities and units library","text":"

    The Study Group 6 (Numerics) discussed the proposal for several hours. The initial feedback was positive. There were some concerns related to the description and design of the affine space abstractions in the library. Besides that, the people in the room liked what they saw.

    We run a few polls in SG6 as well:

    POLL: The syntax number * unit is the right solution for constructing quantities. Not allowing reordering the operands is correct.

    Strongly in Favor In favor Neutral Against Strongly Against 5 4 1 0 1

    POLL: Not defining any UDLs is the right solution.

    No objection to unanimous consent.

    The paper was also briefly discussed in SG18 LEWG Incubator, and the initial feedback was also positive. No polls were taken.

    SG16 Unicode does not meet during ISO C++ Committee F2F meetings. Still, the text output chapter paper was also reviewed by it during an online meeting before Tokyo. We got good feedback and are expected to return with the updated version. No polls were taken.

    "},{"location":"blog/2024/04/15/report-from-the-tokyo-2024-iso-c-committee-meeting/#p30942r1-stdbasic_fixed_string","title":"P30942R1: std::basic_fixed_string","text":"

    In the SG18 LEWG Incubator, before we started to talk about P3045R0, we spent a few hours discussing the design of the std::basic_fixed_string, which is proposed for C++26. The group gave excellent feedback, and if the R2 version addresses it properly, the paper is expected to progress to LEWG (Library Evolution Working Group) in St. Louis.

    Plenty of polls were taken:

    POLL: We should promise more committee time to pursuing std::basic_fixed_string, knowing that our time is scarce and this will leave less time for other work.

    Strongly in Favor In favor Neutral Against Strongly Against 11 0 0 0 0

    POLL: Should the constructor from a string literal be consteval?

    Strongly in Favor In favor Neutral Against Strongly Against 6 3 2 0 0

    POLL: Do we want to add .view()?

    Strongly in Favor In favor Neutral Against Strongly Against 3 5 3 0 0

    POLL: Do we want the .size member to be an integral_constant<size_t, N> (and .empty to be bool_constant<N==0>)?

    Strongly in Favor In favor Neutral Against Strongly Against 5 2 2 2 0

    POLL: Should the index operator[] return a reference to const?

    Strongly in Favor In favor Neutral Against Strongly Against 2 2 3 3 0

    POLL: Should the constructor from a string literal have a precondition that txt[N] == 0?

    Strongly in Favor In favor Neutral Against Strongly Against 6 1 2 0 2"},{"location":"blog/2024/11/25/report-from-the-wroc%C5%82aw-2024-iso-c-committee-meeting/","title":"Report from the Wroc\u0142aw 2024 ISO C++ Committee meeting","text":"

    The Wroc\u0142aw 2024 meeting was another efficient step in the standardization of this library. We've spent the entire day on the joint LEWGI and SG6 discussion and got lots of feedback. We've also introduced std::fixed_string to LEWG for C++26.

    "},{"location":"blog/2024/11/25/report-from-the-wroc%C5%82aw-2024-iso-c-committee-meeting/#p3045r4-quantities-and-units-library","title":"P3045R4: Quantities and units library","text":"

    We have presented the following chapters of our proposal to LEWGI and SG6. We reviewed all the usage examples, discussed composing symbols for derived dimensions and units, and looked into formatting specifications for quantities. We also discussed the minimal scope of the proposal.

    We got plenty of feedback on:

    We were also asked to extend the library to provide text output support for quantity points.

    You can expect all of those changes to appear in the next release.

    "},{"location":"blog/2024/11/25/report-from-the-wroc%C5%82aw-2024-iso-c-committee-meeting/#p30942r5-stdbasic_fixed_string","title":"P30942R5: std::basic_fixed_string","text":"

    The paper was well received. However, Barry Revzin submitted P3380 paper in September. This started a discussion about the scope of this proposal. Should we:

    "},{"location":"getting_started/contributing/","title":"Contributing","text":"

    \ud83d\udc4d\ud83c\udf89 First off, thanks for taking the time to contribute! \ud83c\udf89\ud83d\udc4d

    "},{"location":"getting_started/contributing/#mp-units-documentation","title":"mp-units documentation","text":"

    Before contributing, it is highly recommended to familiarize yourself with our official documentation.

    This file is also a part of it, and this is why it has non-standard Markdown formatting (which can be seen when reading in a regular Markdown renderer). To benefit from full mkdocs rendering, please switch to the Contributing chapter of our documentation.

    "},{"location":"getting_started/contributing/#where-to-start","title":"Where to start?","text":"

    If you are looking for a good issue to start with, please check the following:

    "},{"location":"getting_started/contributing/#gitpod","title":"Gitpod","text":"

    The easiest way to start coding is to jump straight into Gitpod environment. You can either click the button below

    or prefix any mp-units URL (main branch, other branches, issues, PRs, ...) in your web browser with gitpod.io/# (e.g., https://gitpod.io/#https://github.com/mpusz/mp-units).

    The above environment provides you with:

    "},{"location":"getting_started/contributing/#building-testing-and-packaging","title":"Building, testing, and packaging","text":"

    Alternatively, please refer to our official docs for download, build, and install instructions with the below changes if you want to set up a development environment on your local machine.

    "},{"location":"getting_started/contributing/#conan-configuration-properties","title":"Conan configuration properties","text":"user.mp-units.build:all

    Enables compilation of all the source code, including tests and examples. To support this, it requires some additional Conan build dependencies described in Repository directory tree and dependencies. It also runs unit tests during the Conan build (unless tools.build:skip_test configuration property is set to True).

    user.mp-units.build:skip_la

    If user.mp-units.build:all is enabled, among others, Conan installs the external wg21-linear_algebra dependency and enables the compilation of linear algebra-based tests and usage examples. Such behavior can be disabled with this option.

    user.mp-units.analyze:clang-tidy

    Enables clang-tidy analysis.

    "},{"location":"getting_started/contributing/#cmake-options-for-mp-units-project-developers","title":"CMake options for mp-units project developers","text":"MP_UNITS_DEV_BUILD_LA

    2.2.0 \u00b7 ON/OFF (Default: ON)

    Enables building code depending on the linear algebra library.

    MP_UNITS_DEV_IWYU

    2.2.0 \u00b7 ON/OFF (Default: OFF)

    Enables include-what-you-use analysis.

    MP_UNITS_DEV_CLANG_TIDY

    2.2.0 \u00b7 ON/OFF (Default: OFF)

    Enables clang-tidy analysis.

    MP_UNITS_DEV_TIME_TRACE

    2.5.0 \u00b7 NONE/ALL/MODULES/HEADERS (Default: NONE)

    Enables compilation performance data collection with -ftime-trace for clang compilers.

    All our unit tests compile only for headers and never for modules. To allow fair comparison, MODULES and HEADERS do not enable the data collection for unit tests. This means that they affect only the core, systems, and examples.

    Please use ALL to profile unit tests as well.

    "},{"location":"getting_started/contributing/#building-the-entire-repository","title":"Building the entire repository","text":"

    To build all the mp-units source code (with unit tests and examples), you should:

    1. Use the CMakeLists.txt from the top-level directory.
    2. Run Conan with user.mp-units.build:all = True.
    git clone https://github.com/mpusz/mp-units.git && cd mp-units\nconan build . -pr <your_conan_profile> -s compiler.cppstd=23 -c user.mp-units.build:all=True -b missing\n

    The above will download and install all of the dependencies needed for the development of the library, build all of the source code, and run unit tests.

    If you prefer to build the project via CMake rather than Conan, then you should replace the conan build with conan install command and then follow with a regular CMake build and testing:

    conan install . -pr <your_conan_profile> -s compiler.cppstd=23 -c user.mp-units.build:all=True -b missing\ncmake --preset conan-default\ncmake --build --preset conan-release\ncmake --build --preset conan-release --target all_verify_interface_header_sets\ncmake --build --preset conan-release --target test\n

    Hint

    To ensure that we always build all the targets and to save some typing of the Conan commands, we can set the following in the ~/.conan2/global.conf:

    user.mp-units.build:all=True\n
    "},{"location":"getting_started/contributing/#packaging","title":"Packaging","text":"

    To test CMake installation and Conan packaging run:

    conan create . --user <username> --channel <channel> -pr <your_conan_profile> -s compiler.cppstd=23 \\\n               -c user.mp-units.build:all=True -b missing\n

    The above will create a Conan package and run tests provided in ./test_package directory.

    In case you would like to upload mp-units package to the Conan server, do the following:

    conan upload -r <remote-name> --all mp-units/2.2.0@<user>/<channel>\n
    "},{"location":"getting_started/contributing/#building-documentation","title":"Building documentation","text":"

    We are building our documentation using Material for MkDocs. The easiest way to install all the required dependencies is with pip:

    pip install -U mkdocs-material mkdocs-rss-plugin\n

    Additionally, a Cairo Graphics library is required by Material for MkDocs. Please follow the official MkDocs documentation to install it.

    After that, you can either:

    "},{"location":"getting_started/contributing/#generating-api-reference","title":"Generating API reference","text":"

    We need to take a few steps to set up our environment so that we are ready to generate API reference documents.

    First, we need to satisfy the requirements described in https://github.com/cplusplus/draft and https://github.com/Eelis/cxxdraft-htmlgen. On the Ubuntu platform, this is equivalent to the following instructions run from the user's home directory:

    sudo apt install latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended lmodern\nsudo apt install haskell-stack graphviz nodejs npm ghc cabal-install\nnpm install split mathjax-full mathjax-node-sre mathjax-node-cli\ncabal update\n

    On some platforms, installing mathjax-node-cli through npm does update the system's PATH environment variable resulting in tex2html not found errors. In such cases we need to add the .bin folder to the PATH environment variable manually:

    echo \"export PATH=\\\"~/node_modules/.bin:\\$PATH\\\"\" >> ~/.bashrc && source ~/.bashrc\n

    Next, we need to clone the following git repositories:

    For example:

    git clone https://github.com/JohelEGP/jegp.cmake_modules.git --depth=1\ngit clone https://github.com/JohelEGP/draft.git --branch=standardese_sources_base --depth=1\ngit clone https://github.com/JohelEGP/cxxdraft-htmlgen.git --branch=standardese_sources_base --depth=1\n

    Now, we are ready to start building our API reference. First, we need to configure CMake with the following:

    cmake -S docs/api_reference/src -B build/docs/api_reference \\\n      -DCMAKE_MODULE_PATH=\"<path to gh:JohelEGP/jegp.cmake_modules>/modules\" \\\n\u00a0 \u00a0 \u00a0 -DJEGP_STANDARDESE_SOURCES_GIT_REPOSITORY=\"<path to gh:JohelEGP/draft>\" \\\n      -DJEGP_CXXDRAFT_HTMLGEN_GIT_REPOSITORY=\"<path to gh:JohelEGP/cxxdraft-htmlgen>\"\n

    Then we need to build the docs with CMake:

    cmake --build build/docs/api_reference\n

    In the end, we need to move the generated documentation to the docs/api_reference/gen subdirectory:

    mv build/docs/api_reference/mp-units.html docs/api_reference/gen\n

    or just link the entire directory:

    ln -sf ../../build/docs/api_reference/mp-units.html docs/api_reference/gen\n
    "},{"location":"getting_started/contributing/#before-committing-git-changes","title":"Before committing git changes","text":"

    There are a few steps recommended to check before committing and pushing your changes to the git repository.

    "},{"location":"getting_started/contributing/#naming-conventions","title":"Naming conventions","text":"

    Here are the main rules for naming things in this repo:

    "},{"location":"getting_started/contributing/#unified-code-formatting","title":"Unified code formatting","text":"

    A formatting standard is enforced with the pre-commit script. Before committing your changes, please do the following:

    pip install -U pre-commit\npre-commit run --all-files\n

    This will run:

    The script will run on all the files in the repo and will apply the changes in place when needed. After the script is done, please make sure to review and stage all those changes for the git commit.

    "},{"location":"getting_started/contributing/#backward-compatibility","title":"Backward compatibility","text":"

    Before submission, please remember to check if the code compiles fine on the supported compilers. The CI will check it anyway, but it is good to check at least some of the configurations before pushing changes. Especially older compilers can be tricky as those do not have full C++20 conformance. The official list of supported compilers can always be found in the C++ compiler support (API/ABI) chapter of our documentation.

    "},{"location":"getting_started/cpp_compiler_support/","title":"C++ compiler support (API/ABI)","text":"

    Info

    mp-units library tries to provide the best user experience possible with the C++ language. To achieve that, it extensively uses the latest C++ language features.

    Even though the library benefits from the latest C++ versions (if available), C++20 is enough to compile and use all of the library's functionality. Newer features can be hidden behind some preprocessor macros providing a backward-compatible way to use them.

    The table below provides the minimum compiler version required to compile the code using a specific C++ feature:

    C++ Feature C++ version gcc clang apple-clang MSVC Minimum support 20 12+ 16+ && !19 15+ 194+ std::format 20 13+ 17+ 16+ 194+ C++ modules 20 None 17+ None None import std; 23 None 18+ None None Explicit this parameter 23 14+ 18+ None None clang-19 unfixable bug

    Unfortunately, clang-19 does not build mp-units because of an unfixable bug in the compiler.

    MSVC bugs

    MSVC still has a poor C++20 conformance. We had to make many workarounds to our codebase to make it compile on this compiler. Usage of such nasty preprocessor macros degrade the readability and maintainability of our code. This is why we've applied those patches to the main library code but not to unit tests and examples. Those still do not compile on MSVC.

    Here is a list of the most important MSVC bugs:

    Please upvote them so they get a higher fixing priority at Microsoft.

    Important

    Enabling/disabling features listed above may influence the API of the library and the ABI of the customers' projects.

    "},{"location":"getting_started/cpp_compiler_support/#stdformat","title":"std::format","text":""},{"location":"getting_started/cpp_compiler_support/#c-modules","title":"C++ modules","text":"

    Note

    More requirements for C++ modules support can be found in the CMake's documentation.

    "},{"location":"getting_started/cpp_compiler_support/#import-std","title":"import std;","text":""},{"location":"getting_started/cpp_compiler_support/#explicit-this-parameter","title":"Explicit this parameter","text":""},{"location":"getting_started/faq/","title":"Frequently Asked Questions","text":""},{"location":"getting_started/faq/#why-do-we-spell-metre-instead-of-meter","title":"Why do we spell metre instead of meter?","text":"

    This is how the BIPM defines it in the SI Brochure (British English spelling by default).

    "},{"location":"getting_started/faq/#why-dont-we-use-udls-to-create-quantities","title":"Why don't we use UDLs to create quantities?","text":"

    Many reasons make UDLs a poor choice for a physical units library:

    1. UDLs work only with literals (compile-time known values). Our observation is that besides the unit tests, there are only a few compile-time known quantity values used in the production code. Please note that for physical constants, we recommend using Faster-than-lightspeed Constants.

    2. Typical implementations of UDLs tend to always use the widest representation type available. In the case of std::chrono::duration, the following is true:

      using namespace std::chrono_literals;\nauto d1 = 42s;\nauto d2 = 42.s;\nstatic_assert(std::is_same_v<decltype(d1)::rep, std::int64_t>);\nstatic_assert(std::is_same_v<decltype(d2)::rep, long double>);\n

    When such UDL is intermixed in arithmetics with any quantity type of a shorter representation type, it will always expand it to the longest one. In other words, such long type spreads until all types use it everywhere.

    1. While increasing the coverage for the library, we learned that many unit symbols conflict with built-in types or numeric extensions. A few of those are: F (farad), J (joule), W (watt), K (kelvin), d (day), l or L (litre), erg, ergps. Usage of the _ prefix would make it work for mp-units, but in case the library is standardized, those naming collisions would be a big issue. This is why we came up with the _q_ prefix that would become q_ after standardization (e.g., 42q_s), which is not that nice anymore.

    2. UDLs with the same identifiers defined in different namespace can't be disambiguated in the C++ language. If both SI and CGS systems define _q_s UDL for a second unit, then it would not be possible to specify which one to use in case both namespaces are \"imported\" with using directives.

    3. Another bad property of UDLs is that they do not compose. A coherent unit of angular momentum would have a UDL specified as _q_kg_m2_per_s. Now imagine that we want to make every possible user happy. How many variations of that unit would we predefine for differently scaled versions of all unit ingredients?

    4. UDLs are also really expensive to define and specify. Typically, for each unit, we need two definitions. One for integral and another one for floating-point representation. Before the V2 framework, the coherent unit of angular momentum was defined as:

      constexpr auto operator\"\" _q_kg_m2_per_s(unsigned long long l)\n{\n  gsl_Expects(std::in_range<std::int64_t>(l));\n  return angular_momentum<kilogram_metre_sq_per_second, std::int64_t>(static_cast<std::int64_t>(l));\n}\n\nconstexpr auto operator\"\" _q_kg_m2_per_s(long double l)\n{\n  return angular_momentum<kilogram_metre_sq_per_second, long double>(l);\n}\n
    "},{"location":"getting_started/faq/#why-cant-i-create-a-quantity-by-passing-a-number-to-a-constructor","title":"Why can't I create a quantity by passing a number to a constructor?","text":"

    A quantity class template in the mp-units library has no publicly available constructor taking a raw value. Such support is provided by the std::chrono::duration and was pointed out to us as a red flag safety issue by a few parties already.

    Consider the following structure and a code using it:

    struct X {\n  std::vector<std::chrono::milliseconds> vec;\n  // ...\n};\n
    X x;\nx.vec.emplace_back(42);\n

    Everything works fine for years until, at some point, someone changes the structure to:

    struct X {\n  std::vector<std::chrono::microseconds> vec;\n  // ...\n};\n

    The code continues to compile just fine, but all the calculations are off now. This is why we decided to not follow this path.

    In the mp-units library, both a number and a unit have to always be explicitly provided in order to form a quantity.

    Note

    The same applies to the construction of quantity_point using an explicit point origin. To prevent similar safety issues during maintenance, the initialization always requires providing both a quantity and a PointOrigin that we use as a reference point.

    "},{"location":"getting_started/faq/#why-a-dimensionless-quantity-is-not-just-a-fundamental-arithmetic-type","title":"Why a dimensionless quantity is not just a fundamental arithmetic type?","text":"

    In the initial design of this library, the resulting type of division of two quantities was their common representation type:

    static_assert(std::is_same_v<decltype(10 * km / (5 * km)), int>);\n

    First of all, this was consistent with std::chrono::duration behavior. Additional reasoning behind it was not providing a false impression of a strong quantity type for something that looks and feels like a regular number. Also, all of the mathematic and trigonometric functions were working fine out of the box with such representation types, so we did not have to rewrite sin(), cos(), exp(), and others.

    However, the feedback we got from the production usage was that such an approach is really bad for generic programming. It is hard to handle the result of the two quantities' division (or multiplication) as it might be either a quantity or a fundamental type. If we want to raise such a result to some power, we must use units::pow or std::pow depending on the resulting type. Those are only a few issues related to such an approach.

    Moreover, suppose we divide quantities of the same dimension but with units of significantly different magnitudes. In that case, we may end up with a really small or a huge floating-point value, which may result in losing lots of precision. Returning a dimensionless quantity from such cases allows us to benefit from all the properties of scaled units and is consistent with the rest of the library.

    Note

    More information on the current design can be found in the Dimensionless Quantities chapter.

    "},{"location":"getting_started/faq/#why-derived-units-order-is-not-preserved-from-the-multiplication","title":"Why derived units order is not preserved from the multiplication?","text":"

    It might be surprising, but the quantities and units multiplication order does not impact the order of components in the derived unit. Let's try the following example:

    std::println(\"{}\", 42 * kW * h);\nconstexpr auto kWh = kW * h;\nstd::println(\"{}\", 42 * kWh);\n

    The above prints:

    42 h kW\n42 h kW\n

    Some users could expect to see 42 kWh or 42 kW h in the output. It is not the case and for a very good reason. As stated in Simplifying the resulting symbolic expressions, to be able to reason about and simplify units, the library needs to order them in an appropriate order.

    Maybe this default order could be improved a bit, but according to international standards, there is no generic ordering rule. Various quantities use different, often domain-specific, ordering of derived unit components.

    Let's see what SI says here:

    Derived quantity Symbol Derived unit expressed in terms of base units electric field strength V m\u207b\u00b9 kg m s\u207b\u00b3 A\u207b\u00b9 electric charge density C m\u207b\u00b3 A s m\u207b\u00b3 exposure (x- and \u03b3-rays) C kg\u207b\u00b9 A s kg\u207b\u00b9

    However, there is a workaround. A user can define its own named unit for a derived unit and provide the custom symbol text that suits the project's requirements. For example, the above case could be addressed with:

    inline constexpr struct kilowatt_hour final : named_unit<\"kWh\", kW * h> {} kilowatt_hour;\ninline constexpr auto kWh = kilowatt_hour;\n

    With the above, we can refactor the above code to:

    std::println(\"{}\", 42 * kWh);\nstd::println(\"{}\", (42 * kW * h).in(kWh));\n

    Both lines will produce an expected \"42 kWh\" unit in the output.

    Important

    Please note that this makes the entire \"kWh\" a single, indivisible entity that is not subject to simplification rules. This means that 42 * kWh / (2 * h) will result with 21 kWh/h rather than 21 kW. To get the latter, the user needs to explicitly provide a new derived unit:

    std::println(\"{}\", (42 * kWh / (2 * h)).in(kW));\n
    "},{"location":"getting_started/faq/#why-do-the-identifiers-for-concepts-in-the-library-use-camelcase","title":"Why do the identifiers for concepts in the library use CamelCase?","text":"

    Initially, C++20 was meant to use CamelCase for all the concept identifiers. All the concepts from the std::ranges library were merged with such names into the standard document draft. Frustratingly, CamelCase concepts got dropped from the C++ standard at the last moment before releasing C++20. Now, we are facing the predictable consequences of running out of names.

    As long as some concepts in the library could be easily named with a standard_case there are some that are hard to distinguish from the corresponding type names, such as Quantity, QuantityPoint, QuantitySpec, or Reference. This is why we decided to use CamelCase consistently for all the concept identifiers to make it clear when we are talking about a type or concept identifier.

    However, we are aware that this might be a temporary solution. In case the library gets standardized, we can expect the ISO C++ Committee to bikeshed/rename all of the concept identifiers to a standard_case, even if it will result in a harder to understand code.

    Note

    In case you have a good idea of how to rename existing concepts to the standard_case, please let us know in the associated GitHub Issue.

    "},{"location":"getting_started/faq/#why-utf-8-quantity-symbols-are-used-by-default-instead-of-portable-characters","title":"Why UTF-8 quantity symbols are used by default instead of portable characters?","text":"

    Both C++ and ISO 80000 are standardized by the ISO. ISO 80000 and the SI standards specify UTF-8 symbols as the official unit names for some quantities (e.g. \u03a9 symbol for the resistance quantity). As the mp-units library will be proposed for standardization as a part of the C++ Standard Library we have to obey the rules and be consistent with ISO specifications.

    Note

    We do understand engineering reality and the constraints of some environments. This is why the library has the option of Portable Quantity Symbols.

    "},{"location":"getting_started/faq/#why-dont-we-have-cmake-options-to-disable-the-building-of-tests-and-examples","title":"Why don't we have CMake options to disable the building of tests and examples?","text":"

    Over time, many people provided PRs proposing adding options to build tests and examples conditionally. Here are a few examples:

    We admit this is a common practice in the industry, but we also believe this is a bad pattern.

    First, the only need for such options comes when a user wants to use add_subdirectory() in CMake to handle dependencies. Such an approach does not scale and should be discouraged. There is little use for such a practice in times when we have dedicated package managers like Conan.

    The second thing is that our observation is that many people are fixed on disabling \"unneeded\" subdirectories from compilation, but they do not see or address the biggest issue, which is polluting user's build environment with our development-specific settings. Propagating our restrictive compilation flags to user's project is not the best idea as it might cause a lot of harm if this project stops to compile because of that.

    Last but not least, not having those options is on purpose. Top level CMakeLists.txt file should only be used by mp-units developers and contributors as an entry point for the project's development. We want to ensure that everyone will build ALL the code correctly before pushing a commit. Having such options would allow unintended issues to leak to PRs and CI.

    This is why our projects have two entry points:

    Note

    For more details on this please refer to the CMake + Conan: 3 Years Later - Mateusz Pusz lecture that Mateusz Pusz provided at the C++Now 2021 conference.

    "},{"location":"getting_started/installation_and_usage/","title":"Installation And Usage","text":"

    This chapter provides all the necessary information to obtain mp-units and build the user's source code using it.

    "},{"location":"getting_started/installation_and_usage/#obtaining-dependencies","title":"Obtaining dependencies","text":"

    This library assumes that most of the dependencies will be provided by the Conan Package Manager. If you want to obtain required dependencies by other means, some modifications to the library's CMake files might be needed.

    Conan quick intro

    In case you are not familiar with Conan, to install it (or upgrade) just do:

    pip install -U conan\n

    After that, you might need to add a custom profile file for your development environment in ~/.conan2/profiles directory. An example profile can look as follows:

    ~/.conan2/profiles/gcc12
    [settings]\narch=x86_64\nbuild_type=Release\ncompiler=gcc\ncompiler.cppstd=20\ncompiler.libcxx=libstdc++11\ncompiler.version=14\nos=Linux\n\n[conf]\ntools.build:compiler_executables={\"c\": \"gcc-14\", \"cpp\": \"g++-14\"}\n

    Setting the language version

    Please note that the mp-units library requires at least C++20 to be set in a Conan profile or forced via the Conan command line. If we do the former, we will not need to provide -s compiler.cppstd=20 every time we run a Conan command line (as provided in the command line instructions below).

    Using Ninja as a CMake generator for Conan

    It is highly recommended to set Ninja as a CMake generator for Conan. To do so, we could create a ~/.conan2/global.conf file that will set tools.cmake.cmaketoolchain:generator to one of the Ninja generators. For example:

    ~/.conan2/global.conf
    tools.cmake.cmaketoolchain:generator=\"Ninja Multi-Config\"\n

    Separate build folders for different configurations

    ~/.conan2/global.conf file may also set tools.cmake.cmake_layout:build_folder_vars which makes working with several compilers or build configurations easier. For example, the below line will force Conan to generate separate CMake presets and folders for each compiler and C++ standard version:

    ~/.conan2/global.conf
    tools.cmake.cmake_layout:build_folder_vars=[\"settings.compiler\", \"settings.compiler.version\", \"settings.compiler.cppstd\"]\n

    In such a case, we will need to use a configuration-specific preset name in the Conan instructions provided below rather than just conan-default and conan-release (e.g., conan-gcc-13-23 and conan-gcc-13-23-release)

    CMake with presets support

    It is recommended to use at least CMake 3.23 to build this project to benefit from CMake Presets generated by Conan. All build instructions below assume that you have such support. If not, your CMake invocations have to be replaced with something like:

    mkdir build && cd build\ncmake .. -G \"Ninja Multi-Config\" -DCMAKE_TOOLCHAIN_FILE=<path_to_generators_dir>/conan_toolchain.cmake\ncmake --build . --config Release\n

    Tip

    In case you can't use CMake 3.23 but you have access to CMake 3.20 or later, you can append -c tools.cmake.cmaketoolchain.presets:max_schema_version=2 to the conan install command which will force Conan to use an older version of the CMake Presets schema.

    "},{"location":"getting_started/installation_and_usage/#build-options","title":"Build options","text":"

    Note

    Most of the below options are related to the C++ language features available in the compilers. Please refer to the C++ compiler support chapter to learn more about which C++ features are required for each option and which compilers support them.

    "},{"location":"getting_started/installation_and_usage/#conan-options","title":"Conan options","text":"cxx_modules

    2.2.0 \u00b7 True/False (Default: automatically determined from settings)

    Configures CMake to add C++ modules to the list of default targets.

    import_std

    2.3.0 \u00b7 True/False (Default: automatically determined from settings)

    Enables import std; usage.

    std_format

    2.2.0 \u00b7 True/False (Default: automatically determined from settings)

    Enables the usage of std::format and associated facilities for text formatting. If it is not supported, then the {fmt} library is used instead.

    no_crtp

    2.2.0 \u00b7 True/False (Default: automatically determined from settings)

    Removes the need for the usage of the CRTP idiom in the quantity_spec definitions.

    contracts

    2.2.0 \u00b7 none/gsl-lite/ms-gsl (Default: see below)

    Enables checking of preconditions and additional assertions in the code.

    If the automatically determined default for import_std is True, then the contracts option is set to none by default. gsl-lite otherwise.

    freestanding

    2.2.0 \u00b7 True/False (Default: False)

    Configures the library in the freestanding mode. When enabled, the library's source code will build with the compiler's -ffreestanding compilation option without any issues.

    CMake options to set when Conan is not being used"},{"location":"getting_started/installation_and_usage/#cmake-options","title":"CMake options","text":"

    Conan will automatically set all the below CMake options based on its configuration (described above). Manual setting of the below CMake options is only needed when Conan is not being used.

    MP_UNITS_BUILD_AS_SYSTEM_HEADERS

    2.2.0 \u00b7 ON/OFF (Default: OFF)

    Exports library as system headers.

    MP_UNITS_BUILD_CXX_MODULES

    2.2.0 \u00b7 ON/OFF (Default: OFF)

    Adds C++ modules to the list of default targets.

    MP_UNITS_API_STD_FORMAT

    2.2.0 \u00b7 ON/OFF (Default: automatically determined)

    Enables the usage of std::format and associated facilities for text formatting. If it is not supported, then the {fmt} library is used instead.

    MP_UNITS_API_NO_CRTP

    2.2.0 \u00b7 ON/OFF (Default: automatically determined)

    Removes the need for the usage of the CRTP idiom in the quantity_spec definitions.

    MP_UNITS_API_CONTRACTS

    2.2.0 \u00b7 NONE/GSL-LITE/MS-GSL (Default: GSL-LITE)

    Enables checking of preconditions and additional asserts in the code.

    MP_UNITS_API_FREESTANDING

    2.2.0 \u00b7 ON/OFF (Default: OFF)

    Configures the library in the freestanding mode. When enabled, the library's source code should build with the compiler's -ffreestanding compilation option without any issues.

    "},{"location":"getting_started/installation_and_usage/#installation-and-reuse","title":"Installation and reuse","text":"

    There are many different ways of installing/reusing mp-units in your project. Below we mention only a few of many options possible.

    Important: Prefer using Conan if possible

    The easiest and most recommended way to obtain mp-units is with the Conan package manager. See Conan + CMake (release) for a detailed instruction.

    "},{"location":"getting_started/installation_and_usage/#conan-cmake-release","title":"Conan + CMake (release)","text":"

    Tip

    If you are new to the Conan package manager you may want to read Obtaining Dependencies and refer to the Consuming packages chapter of the official Conan documentation for more information.

    mp-units releases are hosted on Conan-Center. The following steps may be performed to obtain an official library release:

    1. Create Conan configuration file (either conanfile.txt or conanfile.py) in your project's top-level directory and add mp-units as a dependency of your project. For example, the simplest file may look as follows:

      conanfile.txtconanfile.py 
      [requires]\nmp-units/2.4.0\n\n[options]\n# The below mp-units options are set to defaults by Conan.\n# Uncomment and set to an explicit value to override the defaults.\n#\n# mp-units*:cxx_modules=True\n# mp-units*:import_std=False\n# mp-units*:std_format=True\n# mp-units*:no_crtp=True\n# mp-units*:contracts=gsl-lite\n# mp-units*:freestanding=False\n\n[layout]\ncmake_layout\n\n[generators]\nCMakeToolchain\nCMakeDeps\n
      from conan import ConanFile\nfrom conan.tools.build import can_run\nfrom conan.tools.cmake import CMake, cmake_layout\n\nclass MPUnitsTestConan(ConanFile):\n    settings = \"os\", \"arch\", \"compiler\", \"build_type\"\n    generators = \"CMakeDeps\", \"CMakeToolchain\"\n\n    def requirements(self):\n        self.requires(\n            \"mp-units/2.4.0\",\n            options={\n                # The below mp-units options are set to defaults by Conan.\n                # Uncomment and set to an explicit value to override the defaults.\n                #\n                # \"cxx_modules\": False,\n                # \"import_std\": False,\n                # \"std_format\": True,\n                # \"no_crtp\": True,\n                # \"contracts\": \"gsl-lite\",\n                # \"freestanding\": False,\n            },\n        )\n\n    def layout(self):\n        cmake_layout(self)\n\n    def build(self):\n        cmake = CMake(self)\n        cmake.configure()\n        cmake.build()\n        if can_run(self):\n            cmake.ctest(cli_args=[\"--output-on-failure\"])\n

    2. Import mp-units and its dependencies definitions with find_package:

      find_package(mp-units REQUIRED)\n

    3. Link your CMake targets with mp-units:

      target_link_libraries(<your_target> <PUBLIC|PRIVATE|INTERFACE> mp-units::mp-units)\n

    4. Download, build, and install Conan dependencies before running the CMake configuration step:

      conanfile.txt or conanfile.pyconanfile.py only 
      conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing\ncmake --preset conan-default\ncmake --build --preset conan-release\ncmake --build --preset conan-release --target test\n
      conan build . -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing\n
    "},{"location":"getting_started/installation_and_usage/#conan-cmake-live-at-head","title":"Conan + CMake (Live At Head)","text":"

    This chapter describes the procedure to Live At Head, which means using the latest stable version of mp-units all the time.

    Note

    Please note that even though the Conan packages that you will be using are generated ONLY for builds that are considered stable (passed our CI tests), some minor regressions may happen (CI and C++ build environments are not perfect yet). Also, please expect that the library interface might, and probably will, change occasionally. Even though we do our best, such changes might not be reflected in the project's documentation right away.

    The procedure is similar to the one described in Conan + CMake (release) with the following differences:

    1. Before starting the previous procedure, add mp-units remote to your Conan configuration:

      conan remote add conan-mpusz https://mpusz.jfrog.io/artifactory/api/conan/conan-oss\n

    2. In your Conan configuration file, provide the package identifier of the mpusz/testing stream:

      conanfile.txtconanfile.py 
      [requires]\nmp-units/2.5.0@mpusz/testing\n\n[options]\n# The below mp-units options are set to defaults by Conan.\n# Uncomment and set to an explicit value to override the defaults.\n#\n# mp-units*:cxx_modules=True\n# mp-units*:import_std=False\n# mp-units*:std_format=True\n# mp-units*:no_crtp=True\n# mp-units*:contracts=gsl-lite\n# mp-units*:freestanding=False\n\n[layout]\ncmake_layout\n\n[generators]\nCMakeToolchain\nCMakeDeps\n
      from conan import ConanFile\nfrom conan.tools.build import can_run\nfrom conan.tools.cmake import CMake, cmake_layout\n\nclass MPUnitsTestConan(ConanFile):\n    settings = \"os\", \"arch\", \"compiler\", \"build_type\"\n    generators = \"CMakeDeps\", \"CMakeToolchain\"\n\n    def requirements(self):\n        self.requires(\n            \"mp-units/2.5.0@mpusz/testing\",\n            options={\n                # The below mp-units options are set to defaults by Conan.\n                # Uncomment and set to an explicit value to override the defaults.\n                #\n                # \"cxx_modules\": False,\n                # \"import_std\": False,\n                # \"std_format\": True,\n                # \"no_crtp\": True,\n                # \"contracts\": \"gsl-lite\",\n                # \"freestanding\": False,\n            },\n        )\n\n    def layout(self):\n        cmake_layout(self)\n\n    def build(self):\n        cmake = CMake(self)\n        cmake.configure()\n        cmake.build()\n        if can_run(self):\n            cmake.ctest(cli_args=[\"--output-on-failure\"])\n

      Tip

      The identifiers of the latest packages can always be found in the project's README file or on the project's Artifactory.

    3. Force Conan to check for updated recipes with -u:

      conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing -u\n
    Alternative installation scenarios"},{"location":"getting_started/installation_and_usage/#copy","title":"Copy","text":"

    As mp-units is a C++ header-only library you can simply copy all needed src/*/include subdirectories to your source tree.

    Note

    In such a case, you are on your own to ensure all the dependencies are installed and their header files can be located during the build. Please also note that some compiler-specific flags are needed to make the code compile without issues.

    "},{"location":"getting_started/installation_and_usage/#copy-cmake","title":"Copy + CMake","text":"

    If you copy the mp-units library source code from the project's ./src directory (not the entire repo from its root), you can reuse CMake targets defined by the library. To do so, you should use CMakeLists.txt file from the ./src directory:

    add_subdirectory(<path_to_mp_units_lib_folder>)\n# ...\ntarget_link_libraries(<your_target> <PUBLIC|PRIVATE|INTERFACE> mp-units::mp-units)\n

    Note

    You are still on your own to make sure all the dependencies are installed and their header and CMake configuration files can be located during the build.

    Important: Library users should not use the top-level CMake file

    Top level CMakeLists.txt file should only be used by mp-units developers and contributors as an entry point for the project's development. ./src/CMakeLists.txt contains only a pure library definition and should be used by the customers that prefer to use CMake's add_subdirectory() to handle the dependencies.

    To learn more about the rationale, please check our FAQ.

    "},{"location":"getting_started/installation_and_usage/#install","title":"Install","text":"

    If you don't want to use Conan in your project and just want to install the mp-units library on your file system, and use find_package(mp-units) from another repository to find it; it is enough to perform the following steps:

    conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing\nmv CMakeUserPresets.json src\ncd src\ncmake --preset conan-default -DCMAKE_INSTALL_PREFIX=<your_installation_path>\ncmake --build --preset conan-release --target install\n
    "},{"location":"getting_started/introduction/","title":"Introduction","text":"

    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 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 version 2.0 of mp-units were provided in detail by Mateusz Pusz in the \"The Power of C++ Templates With mp-units: Lessons Learned & a New Library Design\" talk at the C++ on Sea 2023 conference.

    "},{"location":"getting_started/introduction/#open-source","title":"Open Source","text":"

    mp-units is Free and Open Source, with a permissive MIT license. 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.

    "},{"location":"getting_started/introduction/#with-the-users-experience-in-mind","title":"With the User's Experience in Mind","text":"

    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 does 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:

    Important: It is all about errors

    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 that won't compile with a huge error log. Physical quantities and units libraries are different. Generation of compile-time errors is the main reason to use such a library.

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

    Here is a small example of operations possible on scalar quantities:

    C++ modulesHeader files 
    import mp_units;\n\nusing namespace mp_units;\nusing namespace mp_units::si::unit_symbols;\n\n// simple numeric operations\nstatic_assert(10 * km / 2 == 5 * km);\n\n// conversions to common units\nstatic_assert(1 * h == 3600 * s);\nstatic_assert(1 * km + 1 * m == 1001 * m);\n\n// derived quantities\nstatic_assert(1 * km / (1 * s) == 1000 * m / s);\nstatic_assert(2 * km / h * (2 * h) == 4 * km);\nstatic_assert(2 * km / (2 * km / h) == 1 * h);\n\nstatic_assert(2 * m * (3 * m) == 6 * m2);\n\nstatic_assert(10 * km / (5 * km) == 2);\n\nstatic_assert(1000 / (1 * s) == 1 * kHz);\n
    #include <mp-units/systems/si.h>\n\nusing namespace mp_units;\nusing namespace mp_units::si::unit_symbols;\n\n// simple numeric operations\nstatic_assert(10 * km / 2 == 5 * km);\n\n// conversions to common units\nstatic_assert(1 * h == 3600 * s);\nstatic_assert(1 * km + 1 * m == 1001 * m);\n\n// derived quantities\nstatic_assert(1 * km / (1 * s) == 1000 * m / s);\nstatic_assert(2 * km / h * (2 * h) == 4 * km);\nstatic_assert(2 * km / (2 * km / h) == 1 * h);\n\nstatic_assert(2 * m * (3 * m) == 6 * m2);\n\nstatic_assert(10 * km / (5 * km) == 2);\n\nstatic_assert(1000 / (1 * s) == 1 * kHz);\n

    Try it on Compiler Explorer

    This library requires some C++20 features (concepts and constraints, classes as NTTP, ...). Thanks to them, a user gets a powerful but still easy-to-use interface where all unit conversions and dimensional analysis can be performed without sacrificing accuracy. Please see the below example for a quick preview of basic library features:

    C++ modulesHeader files 
    #include <format>\n#include <iomanip>\n#include <iostream>\n#include <print>\nimport mp_units;\n\nusing namespace mp_units;\n\nconstexpr QuantityOf<isq::speed> auto avg_speed(QuantityOf<isq::length> auto d,\n                                                QuantityOf<isq::time> auto t)\n{\n  return d / t;\n}\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n  using namespace mp_units::international::unit_symbols;\n\n  constexpr quantity v1 = 110 * km / h;\n  constexpr quantity v2 = 70 * mph;\n  constexpr quantity v3 = avg_speed(220. * isq::distance[km], 2 * h);\n  constexpr quantity v4 = avg_speed(isq::distance(140. * mi), 2 * h);\n  constexpr quantity v5 = v3.in(m / s);\n  constexpr quantity v6 = value_cast<m / s>(v4);\n  constexpr quantity v7 = value_cast<int>(v6);\n\n  std::cout << v1 << '\\n';                                        // 110 km/h\n  std::cout << std::setw(10) << std::setfill('*') << v2 << '\\n';  // ***70 mi/h\n  std::cout << std::format(\"{:*^10}\\n\", v3);                      // *110 km/h*\n  std::println(\"{:%N in %U of %D}\", v4);                          // 70 in mi/h of LT\u207b\u00b9\n  std::println(\"{::N[.2f]}\", v5);                                 // 30.56 m/s\n  std::println(\"{::N[.2f]U[dn]}\", v6);                            // 31.29 m\u22c5s\u207b\u00b9\n  std::println(\"{:%N}\", v7);                                      // 31\n}\n
    #include <mp-units/systems/international.h>\n#include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n#include <format>\n#include <iomanip>\n#include <iostream>\n#include <print>\n\nusing namespace mp_units;\n\nconstexpr QuantityOf<isq::speed> auto avg_speed(QuantityOf<isq::length> auto d,\n                                                QuantityOf<isq::time> auto t)\n{\n  return d / t;\n}\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n  using namespace mp_units::international::unit_symbols;\n\n  constexpr quantity v1 = 110 * km / h;\n  constexpr quantity v2 = 70 * mph;\n  constexpr quantity v3 = avg_speed(220. * isq::distance[km], 2 * h);\n  constexpr quantity v4 = avg_speed(isq::distance(140. * mi), 2 * h);\n  constexpr quantity v5 = v3.in(m / s);\n  constexpr quantity v6 = value_cast<m / s>(v4);\n  constexpr quantity v7 = value_cast<int>(v6);\n\n  std::cout << v1 << '\\n';                                        // 110 km/h\n  std::cout << std::setw(10) << std::setfill('*') << v2 << '\\n';  // ***70 mi/h\n  std::cout << std::format(\"{:*^10}\\n\", v3);                      // *110 km/h*\n  std::println(\"{:%N in %U of %D}\", v4);                          // 70 in mi/h of LT\u207b\u00b9\n  std::println(\"{::N[.2f]}\", v5);                                 // 30.56 m/s\n  std::println(\"{::N[.2f]U[dn]}\", v6);                            // 31.29 m\u22c5s\u207b\u00b9\n  std::println(\"{:%N}\", v7);                                      // 31\n}\n

    Try it on Compiler Explorer

    Note

    More code examples can be found in the Examples chapter.

    "},{"location":"getting_started/project_structure/","title":"Project structure","text":"

    This chapter provides a high level overview of the project to make it easier to navigate, build, and use.

    "},{"location":"getting_started/project_structure/#cmake-projects-and-dependencies","title":"CMake projects and dependencies","text":"

    The GitHub repository contains three independent CMake-based projects:

    Important: Library users should not use the top-level CMake file

    Top level CMakeLists.txt file should only be used by mp-units developers and contributors as an entry point for the project's development. We want to ensure that everyone will build ALL the code correctly before pushing a commit. Having such options would allow unintended issues to leak to PRs and CI.

    This is why our projects have two entry points:

    To learn more about the rationale, please check our FAQ.

    "},{"location":"getting_started/project_structure/#modules","title":"Modules","text":"

    The mp-units library provides the following C++ modules:

    flowchart TD\n    mp_units --- mp_units.systems --- mp_units.core
    C++ Module CMake Target Contents mp_units.core mp-units::core Core library framework and systems-independent utilities mp_units.systems mp-units::systems All the systems of quantities and units mp_units mp-units::mp-units Core + Systems

    Note

    C++ modules are provided within the package only when:

    "},{"location":"getting_started/project_structure/#header-files","title":"Header files","text":"

    All of the project's header files can be found in the mp-units/... subdirectory.

    "},{"location":"getting_started/project_structure/#core-library","title":"Core library","text":" More details

    More detailed header files can be found in subfolders which typically should not be included by the end users:

    "},{"location":"getting_started/project_structure/#systems-and-associated-utilities","title":"Systems and associated utilities","text":"

    The systems definitions can be found in the mp-units/systems/... subdirectory:

    "},{"location":"getting_started/project_structure/#systems-of-quantities","title":"Systems of quantities","text":" Tip: Improving compile times

    mp-units/systems/isq.h might be expensive to compile in every translation unit. There are some smaller, domain targeted files available for explicit inclusion in the mp-units/systems/isq/... subdirectory.

    "},{"location":"getting_started/project_structure/#systems-of-units","title":"Systems of units","text":" Tip: Improving compile times

    mp-units/systems/si.h might be expensive to compile in every translation unit. There are some smaller files available for explicit inclusion in the mp-units/systems/si/... subdirectory.

    mp-units/systems/si/unit_symbols.h is the most expensive to include.

    "},{"location":"getting_started/quick_start/","title":"Quick Start","text":"

    This chapter provides a quick introduction to get you started with mp-units. Much more details can be found in our User's Guide.

    "},{"location":"getting_started/quick_start/#quantities","title":"Quantities","text":"

    A quantity is a concrete amount of a unit representing a quantity type of a specified dimension with a specific representation. It is represented in the library with a quantity class template.

    The SI Brochure says:

    SI Brochure

    The value of the quantity is the product of the number and the unit. The space between the number and the unit is regarded as a multiplication sign (just as a space between units implies multiplication).

    Following the above, the value of a quantity in the mp-units library is created by multiplying a number with a predefined unit:

    C++ modulesHeader files 
    import mp_units;\n\nusing namespace mp_units;\n\nquantity q = 42 * si::metre / si::second;\n
    #include <mp-units/systems/si.h>\n\nusing namespace mp_units;\n\nquantity q = 42 * si::metre / si::second;\n

    Info

    In case someone doesn't like the multiply syntax or there is an ambiguity between operator* provided by this and other libraries, there are two other ways to create a quantity:

    1. delta construction helper:

      C++ modulesHeader files 
      import mp_units;\n\nusing namespace mp_units;\n\nquantity q = delta<si::metre / si::second>(42);\n
      #include <mp-units/systems/si.h>\n\nusing namespace mp_units;\n\nquantity q = delta<si::metre / si::second>(42);\n

    2. A two-parameter constructor:

      C++ modulesHeader files 
      import mp_units;\n\nusing namespace mp_units;\n\nquantity q{42, si::metre / si::second};\n
      #include <mp-units/systems/si.h>\n\nusing namespace mp_units;\n\nquantity q{42, si::metre / si::second};\n

    The above creates an instance of quantity<derived_unit<si::metre, per<si::second>>{}, int>. The same can be obtained using optional unit symbols:

    C++ modulesHeader files 
    import mp_units;\n\nusing namespace mp_units;\nusing namespace mp_units::si::unit_symbols;\n\nquantity q = 42 * m / s;\n
    #include <mp-units/systems/si.h>\n\nusing namespace mp_units;\nusing namespace mp_units::si::unit_symbols;\n\nquantity q = 42 * m / s;\n

    Important

    Unit symbols introduce a lot of short identifiers into the current scope, which may cause naming collisions with unrelated but already existing identifiers in the code base. This is why unit symbols are opt-in and typically should be imported only in the context where they are being used (e.g., function scope).

    A user has several options here to choose from depending on the required scenario and possible naming conflicts:

    using-directiveusing-declarationcustom short identifierunit names

    Explicitly \"import\" all of the symbols of a specific system of units from a dedicated unit_symbols namespace with a using-directive:

    using namespace mp_units;\n\nvoid foo(double speed_m_s)\n{\n  // imports all the SI symbols at once\n  using namespace si::unit_symbols;\n  quantity speed = speed_m_s * m / s;\n  // ...\n}\n

    Note

    This solution is perfect for small and isolated scopes but can cause surprising issues when used in larger scopes or when used for the entire program namespace.

    There are 29 named units in SI, and each of them has many prefixed variations (e.g., ng, kcd, ...). It is pretty easy to introduce a name collision with those.

    Selectively bring only the required and not-conflicting symbols with using-declarations:

    using namespace mp_units;\n\nvoid foo(double N)\n{\n  // 'N' function parameter would collide with the SI symbol for Newton, so we only bring what we need\n  using si::unit_symbols::m;\n  using si::unit_symbols::s;\n  quantity speed = N * m / s;\n  // ...\n}\n

    Specify a custom not conflicting unit identifier for a unit:

    using namespace mp_units;\n\nvoid foo(double speed_m_s)\n{\n  // names of some local variables are conflicting with the symbols we want to use\n  auto m = ...;\n  auto s = ...;\n\n  constexpr Unit auto mps = si::metre / si::second;\n  quantity speed = speed_m_s * mps;\n}\n

    Full unit names are straightforward to use and often provide the most readable code:

    using namespace mp_units;\n\nvoid foo(double m, double s)\n{\n  quantity speed = m * si::metre / (s * si::second);\n  // ...\n}\n

    Quantities of the same kind can be added, subtracted, and compared to each other:

    C++ modulesHeader files 
    import mp_units;\n\nusing namespace mp_units;\nusing namespace mp_units::si::unit_symbols;\n\nstatic_assert(1 * km + 50 * m == 1050 * m);\n
    #include <mp-units/systems/si.h>\n\nusing namespace mp_units;\nusing namespace mp_units::si::unit_symbols;\n\nstatic_assert(1 * km + 50 * m == 1050 * m);\n

    Various quantities can be multiplied or divided by each other:

    static_assert(140 * km / (2 * h) == 70 * km / h);\n

    Note

    In case you wonder why this library does not use UDLs to create quantities, please check our FAQ.

    "},{"location":"getting_started/quick_start/#quantity-points","title":"Quantity points","text":"

    The quantity point specifies an absolute quantity with respect to an origin. If no origin is provided explicitly, an implicit one will be provided by the library.

    Together with quantities, they model The Affine Space.

    Quantity points should be used in all places where adding two values is meaningless (e.g., temperature points, timestamps, altitudes, readouts from the car's odometer, etc.).

    The set of operations that can be done on quantity points is limited compared to quantities. This introduces an additional type-safety.

    C++ modulesHeader files 
    #include <print>\nimport mp_units;\n\nint main()\n{\n  using namespace mp_units;\n  using namespace mp_units::si::unit_symbols;\n  using namespace mp_units::usc::unit_symbols;\n\n  quantity_point temp = point<deg_C>(20.);\n  std::println(\"Temperature: {} ({})\",\n               temp.quantity_from_zero(),\n               temp.in(deg_F).quantity_from_zero());\n}\n
    #include <mp-units/systems/si.h>\n#include <mp-units/systems/usc.h>\n#include <print>\n\nint main()\n{\n  using namespace mp_units;\n  using namespace mp_units::si::unit_symbols;\n  using namespace mp_units::usc::unit_symbols;\n\n  quantity_point temp = point<deg_C>(20.);\n  std::println(\"Temperature: {} ({})\",\n               temp.quantity_from_zero(),\n               temp.in(deg_F).quantity_from_zero());\n}\n

    The above outputs:

    Temperature: 20 \u2103 (68 \u2109)\n

    Info

    Check The Affine Space chapter to learn more about quantity points.

    "},{"location":"users_guide/terms_and_definitions/","title":"Terms and Definitions","text":"

    The mp-units project consistently uses the official metrology vocabulary defined by the ISO and BIPM. You can find essential project-related definitions in our documentation's \"Glossary\" chapter. Even more, terms are provided in the official metrology vocabulary of the ISO and BIPM.

    Tip

    Please familiarize yourself with terms from \"Glossary\" to better understand the documentation and improve domain-related communication and discussions.

    "},{"location":"users_guide/examples/avg_speed/","title":"avg_speed","text":"

    Try it on Compiler Explorer

    Let's continue the previous example. This time, our purpose will not be to showcase as many library features as possible, but we will scope on different interfaces one can provide with the mp-units. We will also describe some advantages and disadvantages of presented solutions.

    First, we either import a module or include all the necessary header files and import all the identifiers from the mp_units namespace:

    avg_speed.cpp
    #ifdef MP_UNITS_IMPORT_STD\nimport std;\n#else\n#include <exception>\n#include <iostream>\n#endif\n#ifdef MP_UNITS_MODULES\nimport mp_units;\n#else\n#include <mp-units/systems/cgs.h>\n#include <mp-units/systems/international.h>\n#include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n#endif\n\nnamespace {\n\nusing namespace mp_units;\n

    Next, we define two functions calculating average speed based on quantities of fixed units and integral and floating-point representation types, respectively, and a third function that we introduced in the previous example:

    avg_speed.cpp
    constexpr quantity<si::metre / si::second, int> fixed_int_si_avg_speed(quantity<si::metre, int> d,\n                                                                       quantity<si::second, int> t)\n{\n  return d / t;\n}\n\nconstexpr quantity<si::metre / si::second> fixed_double_si_avg_speed(quantity<si::metre> d, quantity<si::second> t)\n{\n  return d / t;\n}\n\nconstexpr QuantityOf<isq::speed> auto avg_speed(QuantityOf<isq::length> auto d, QuantityOf<isq::time> auto t)\n{\n  return d / t;\n}\n

    We also added a simple utility to print our results:

    avg_speed.cpp
    template<QuantityOf<isq::length> D, QuantityOf<isq::time> T, QuantityOf<isq::speed> V>\nvoid print_result(D distance, T duration, V speed)\n{\n  const auto result_in_kmph = speed.force_in(si::kilo<si::metre> / non_si::hour);\n  std::cout << \"Average speed of a car that makes \" << distance << \" in \" << duration << \" is \" << result_in_kmph\n            << \".\\n\";\n}\n

    Now, let's analyze how those three utility functions behave with different sets of arguments. First, we are going to use quantities of SI units and integral representation:

    avg_speed.cpp
    void example()\n{\n  using namespace mp_units::si::unit_symbols;\n\n  // SI (int)\n  {\n    constexpr auto distance = 220 * km;\n    constexpr auto duration = 2 * h;\n\n    std::cout << \"SI units with 'int' as representation\\n\";\n\n    print_result(distance, duration, fixed_int_si_avg_speed(distance, duration));\n    print_result(distance, duration, fixed_double_si_avg_speed(distance, duration));\n    print_result(distance, duration, avg_speed(distance, duration));\n  }\n

    The above provides the following output:

    SI units with 'int' as representation\nAverage speed of a car that makes 220 km in 2 h is 108 km/h.\nAverage speed of a car that makes 220 km in 2 h is 110 km/h.\nAverage speed of a car that makes 220 km in 2 h is 110 km/h.\n

    Please note that in the first two cases, we must convert length from km to m and time from h to s. The converted values are used to calculate speed in m/s which is then again converted to the one in km/h. Those conversions not only impact the application's runtime performance but may also affect the precision of the final result. Such truncation can be easily observed in the first case where we deal with integral representation types (the resulting speed is 108 km/h).

    The second scenario is really similar to the previous one, but this time, function arguments have floating-point representation types:

    avg_speed.cpp
      // SI (double)\n  {\n    constexpr auto distance = 220. * km;\n    constexpr auto duration = 2. * h;\n\n    std::cout << \"\\nSI units with 'double' as representation\\n\";\n\n    // conversion from a floating-point to an integral type is a truncating one so an explicit cast is needed\n    print_result(distance, duration, fixed_int_si_avg_speed(value_cast<int>(distance), value_cast<int>(duration)));\n    print_result(distance, duration, fixed_double_si_avg_speed(distance, duration));\n    print_result(distance, duration, avg_speed(distance, duration));\n  }\n

    Conversion from floating-point to integral representation types is considered value-truncating and that is why now, in the first case, we need an explicit call to value_cast<int>.

    In the text output, we can observe that, again, the resulting value gets truncated during conversions in the first cast:

    SI units with 'double' as representation\nAverage speed of a car that makes 220 km in 2 h is 108 km/h.\nAverage speed of a car that makes 220 km in 2 h is 110 km/h.\nAverage speed of a car that makes 220 km in 2 h is 110 km/h.\n

    Next, let's do the same for integral and floating-point representations, but this time using international mile:

    avg_speed.cpp
      // International mile (int)\n  {\n    using namespace mp_units::international::unit_symbols;\n\n    constexpr auto distance = 140 * mi;\n    constexpr auto duration = 2 * h;\n\n    std::cout << \"\\nInternational mile with 'int' as representation\\n\";\n\n    // it is not possible to make a lossless conversion of miles to meters on an integral type\n    // (explicit cast needed)\n    print_result(distance, duration, fixed_int_si_avg_speed(distance.force_in(m), duration));\n    print_result(distance, duration, fixed_double_si_avg_speed(distance, duration));\n    print_result(distance, duration, avg_speed(distance, duration));\n  }\n\n  // International mile (double)\n  {\n    using namespace mp_units::international::unit_symbols;\n\n    constexpr auto distance = 140. * mi;\n    constexpr auto duration = 2. * h;\n\n    std::cout << \"\\nInternational mile with 'double' as representation\\n\";\n\n    // conversion from a floating-point to an integral type is a truncating one so an explicit cast is needed\n    // also it is not possible to make a lossless conversion of miles to meters on an integral type\n    // (explicit cast needed)\n    print_result(distance, duration, fixed_int_si_avg_speed(value_cast<m, int>(distance), value_cast<int>(duration)));\n    print_result(distance, duration, fixed_double_si_avg_speed(distance, duration));\n    print_result(distance, duration, avg_speed(distance, duration));\n  }\n

    One important difference here is the fact that as it is not possible to make a lossless conversion of miles to meters on a quantity using an integral representation type, so this time, we need a value_cast<m, int> to force it.

    If we check the text output of the above, we will see the following:

    International mile with 'int' as representation\nAverage speed of a car that makes 140 mi in 2 h is 111 km/h.\nAverage speed of a car that makes 140 mi in 2 h is 112.654 km/h.\nAverage speed of a car that makes 140 mi in 2 h is 112 km/h.\n\nInternational mile with 'double' as representation\nAverage speed of a car that makes 140 mi in 2 h is 111 km/h.\nAverage speed of a car that makes 140 mi in 2 h is 112.654 km/h.\nAverage speed of a car that makes 140 mi in 2 h is 112.654 km/h.\n

    Please note how the first and third results get truncated using integral representation types.

    In the end, we repeat the scenario for CGS units:

    avg_speed.cpp
      // CGS (int)\n  {\n    constexpr auto distance = 22'000'000 * cgs::centimetre;\n    constexpr auto duration = 7200 * cgs::second;\n\n    std::cout << \"\\nCGS units with 'int' as representation\\n\";\n\n    // it is not possible to make a lossless conversion of centimeters to meters on an integral type\n    // (explicit cast needed)\n    print_result(distance, duration, fixed_int_si_avg_speed(distance.force_in(m), duration));\n    print_result(distance, duration, fixed_double_si_avg_speed(distance, duration));\n    print_result(distance, duration, avg_speed(distance, duration));\n  }\n\n  // CGS (double)\n  {\n    constexpr auto distance = 22'000'000. * cgs::centimetre;\n    constexpr auto duration = 7200. * cgs::second;\n\n    std::cout << \"\\nCGS units with 'double' as representation\\n\";\n\n    // conversion from a floating-point to an integral type is a truncating one so an explicit cast is needed\n    // it is not possible to make a lossless conversion of centimeters to meters on an integral type\n    // (explicit cast needed)\n    print_result(distance, duration, fixed_int_si_avg_speed(value_cast<m, int>(distance), value_cast<int>(duration)));\n\n    print_result(distance, duration, fixed_double_si_avg_speed(distance, duration));\n    print_result(distance, duration, avg_speed(distance, duration));\n  }\n}\n\n}  // namespace\n

    Again, we observe value_cast being used in the same places and consistent truncation errors in the text output:

    CGS units with 'int' as representation\nAverage speed of a car that makes 22000000 cm in 7200 s is 108 km/h.\nAverage speed of a car that makes 22000000 cm in 7200 s is 110 km/h.\nAverage speed of a car that makes 22000000 cm in 7200 s is 109 km/h.\n\nCGS units with 'double' as representation\nAverage speed of a car that makes 2.2e+07 cm in 7200 s is 108 km/h.\nAverage speed of a car that makes 2.2e+07 cm in 7200 s is 110 km/h.\nAverage speed of a car that makes 2.2e+07 cm in 7200 s is 110 km/h.\n

    The example file ends with a simple main() function:

    avg_speed.cpp
    int main()\n{\n  try {\n    example();\n  } catch (const std::exception& ex) {\n    std::cerr << \"Unhandled std exception caught: \" << ex.what() << '\\n';\n  } catch (...) {\n    std::cerr << \"Unhandled unknown exception caught\\n\";\n  }\n}\n
    ","tags":["CGS System","International System"]},{"location":"users_guide/examples/hello_units/","title":"hello_units","text":"

    Try it on Compiler Explorer

    This is a really simple example showcasing the features of the mp-units library.

    First, we either import the mp_units module or include the headers for:

    hello_units.cpp
    #include <mp-units/compat_macros.h>\n#include <mp-units/ext/format.h>\n#ifdef MP_UNITS_IMPORT_STD\nimport std;\n#else\n#include <iomanip>\n#include <iostream>\n#endif\n#ifdef MP_UNITS_MODULES\nimport mp_units;\n#else\n#include <mp-units/systems/international.h>\n#include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n#endif\n

    Also, to shorten the definitions, we \"import\" all the symbols from the mp_units namespace.

    hello_units.cpp
    using namespace mp_units;\n

    Next, we define a simple function that calculates the average speed based on the provided arguments of length and time:

    hello_units.cpp
    constexpr QuantityOf<isq::speed> auto avg_speed(QuantityOf<isq::length> auto d, QuantityOf<isq::time> auto t)\n{\n  return d / t;\n}\n

    The above function template takes any quantities implicitly convertible to isq::length and isq::time, respectively. Those quantities can use any compatible unit and a representation type. The function returns a result of a straightforward equation and ensures that its quantity type is implicitly convertible to isq::speed.

    Tip

    Besides verifying the type returned from the function, constraining a generic return type is beneficial for users of such a function as it provides more information of what to expect from a function than just using auto.

    hello_units.cpp
    int main()\n{\n  using namespace mp_units::si::unit_symbols;\n  using namespace mp_units::international::unit_symbols;\n

    The above lines explicitly opt into using unit symbols from two systems of units. As this introduces a lot of short identifiers into the current scope, it is not done implicitly while including a header file.

    hello_units.cpp
      constexpr quantity v1 = 110 * km / h;\n  constexpr quantity v2 = 70 * mph;\n  constexpr quantity v3 = avg_speed(220. * km, 2 * h);\n  constexpr quantity v4 = avg_speed(isq::distance(140. * mi), 2 * isq::duration[h]);\n  constexpr quantity v5 = v3.in(m / s);\n  constexpr quantity v6 = value_cast<m / s>(v4);\n  constexpr quantity v7 = value_cast<int>(v6);\n
    hello_units.cpp
      std::cout << v1 << '\\n';                                           // 110 km/h\n  std::cout << std::setw(10) << std::setfill('*') << v2 << '\\n';     // ***70 mi/h\n  std::cout << MP_UNITS_STD_FMT::format(\"{:*^10}\\n\", v3);            // *110 km/h*\n  std::cout << MP_UNITS_STD_FMT::format(\"{:%N in %U of %D}\\n\", v4);  // 70 in mi/h of LT\u207b\u00b9\n  std::cout << MP_UNITS_STD_FMT::format(\"{::N[.2f]}\\n\", v5);         // 30.56 m/s\n  std::cout << MP_UNITS_STD_FMT::format(\"{::N[.2f]U[dn]}\\n\", v6);    // 31.29 m\u22c5s\u207b\u00b9\n  std::cout << MP_UNITS_STD_FMT::format(\"{:%N}\\n\", v7);              // 31\n}\n

    The above presents various ways to print a quantity. Both stream insertion operations and std::format facilities are supported.

    Tip

    MP_UNITS_STD_FMT is used for compatibility reasons. If a specific compiler does not support std::format or a user prefers to use the {fmt} library, this macro will resolve to fmt namespace. Otherwise, the std namespace will be used.

    More about it can be found in the Wide Compatibility chapter.

    ","tags":["International System","Text Formatting"]},{"location":"users_guide/examples/hw_voltage/","title":"hw_voltage","text":"

    Try it on Compiler Explorer

    As it was stated in The Affine Space chapter, every measurement can (and probably should) be modelled as a quantity_point. This is a perfect example of such a use case.

    This example implements a simplified scenario of measuring voltage read from hardware through a mapped 16-bits register. The actual voltage range of [-10 V, 10 V] is mapped to [-32767, 32767] on hardware. Translation of the value requires not only scaling of the value but also applying of an offset.

    First we include all the dependencies:

    hw_voltage.cpp
    #include <mp-units/compat_macros.h>\n#include <mp-units/ext/format.h>\n#ifdef MP_UNITS_IMPORT_STD\nimport std;\n#else\n#include <iostream>\n#include <optional>\n#endif\n#ifdef MP_UNITS_MODULES\nimport mp_units;\n#else\n#include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n#endif\n\nusing namespace mp_units;\n

    Next, we specify the real measurement voltage range to be in the range of [-10, 10]:

    hw_voltage.cpp
    // real voltage range\ninline constexpr int min_voltage = -10;\ninline constexpr int max_voltage = 10;\ninline constexpr int voltage_range = max_voltage - min_voltage;\n

    and provide a storage type and special values for the hardware representation:

    hw_voltage.cpp
    // hardware encoding of voltage\nusing voltage_hw_t = std::uint16_t;\ninline constexpr voltage_hw_t voltage_hw_error = std::numeric_limits<voltage_hw_t>::max();\ninline constexpr voltage_hw_t voltage_hw_min = 0;\ninline constexpr voltage_hw_t voltage_hw_max = voltage_hw_error - 1;\ninline constexpr voltage_hw_t voltage_hw_range = voltage_hw_max - voltage_hw_min;\ninline constexpr voltage_hw_t voltage_hw_zero = voltage_hw_range / 2;\n

    Finally, we define a quantity point origin, an offset unit that scales the value and uses this origin to offset the zero of the sale, and a dedicated quantity point alias using those:

    hw_voltage.cpp
    inline constexpr struct hw_voltage_origin final :\n  relative_point_origin<point<si::volt>(min_voltage)> {} hw_voltage_origin;\n\ninline constexpr struct hw_voltage_unit final :\n  named_unit<\"hwV\", mag_ratio<voltage_range, voltage_hw_range> * si::volt, hw_voltage_origin> {} hw_voltage_unit;\n\nusing hw_voltage_quantity_point = quantity_point<hw_voltage_unit, hw_voltage_origin, voltage_hw_t>;\n

    Now, when everything is ready, we can simulate mapping of our hardware register, and provide a helper function that will read the value and construct a quantity point from the obtained copy:

    hw_voltage.cpp
    // mapped HW register\nvolatile voltage_hw_t hw_voltage_value;\n\nstd::optional<hw_voltage_quantity_point> read_hw_voltage()\n{\n  voltage_hw_t local_copy = hw_voltage_value;\n  if (local_copy == voltage_hw_error) return std::nullopt;\n  return point<hw_voltage_unit>(local_copy);\n}\n

    We also provide a simple print helper for our quantity points:

    hw_voltage.cpp
    void print(QuantityPoint auto qp)\n{\n  std::cout << MP_UNITS_STD_FMT::format(\"{:10} ({:5})\", qp.quantity_from_zero(),\n                                        value_cast<double, si::volt>(qp).quantity_from_zero());\n}\n

    In the main function we simulate setting of 3 values by our hardware. Each of them is read and printed in the voltage unit used on the hardware as well as in the standard SI unit:

    hw_voltage.cpp
    int main()\n{\n  // simulate reading of 3 values from the hardware\n  hw_voltage_value = voltage_hw_min;\n  quantity_point qp1 = read_hw_voltage().value();\n  hw_voltage_value = voltage_hw_zero;\n  quantity_point qp2 = read_hw_voltage().value();\n  hw_voltage_value = voltage_hw_max;\n  quantity_point qp3 = read_hw_voltage().value();\n\n  print(qp1);\n  print(qp2);\n  print(qp3);\n}\n

    The above program results with the following text output:

         0 hwV (-10 V)\n 32767 hwV (  0 V)\n 65534 hwV ( 10 V)\n
    ","tags":["Affine Space","Embedded","Text Formatting"]},{"location":"users_guide/examples/si_constants/","title":"si_constants","text":"

    Try it on Compiler Explorer

    The next example presents all the seven defining constants of the SI system. We can observe how Faster-than-lightspeed Constants work in practice.

    si_constants.cpp
    #include <mp-units/compat_macros.h>\n#include <mp-units/ext/format.h>\n#ifdef MP_UNITS_IMPORT_STD\nimport std;\n#else\n#include <iostream>\n#endif\n#ifdef MP_UNITS_MODULES\nimport mp_units;\n#else\n#include <mp-units/systems/si.h>\n#endif\n

    As always, we start with the inclusion of all the needed header files. The main part of the example prints all of the SI-defining constants:

    si_constants.cpp
    int main()\n{\n  using namespace mp_units;\n  using namespace mp_units::si;\n  using namespace mp_units::si::unit_symbols;\n\n  std::cout << \"The seven defining constants of the SI and the seven corresponding units they define:\\n\";\n  std::cout << MP_UNITS_STD_FMT::format(\"- hyperfine transition frequency of Cs: {} = {::N[.0]}\\n\",\n                                        1. * si2019::hyperfine_structure_transition_frequency_of_cs,\n                                        (1. * si2019::hyperfine_structure_transition_frequency_of_cs).in(Hz));\n  std::cout << MP_UNITS_STD_FMT::format(\"- speed of light in vacuum:             {} = {::N[.0]}\\n\",\n                                        1. * si2019::speed_of_light_in_vacuum,\n                                        (1. * si2019::speed_of_light_in_vacuum).in(m / s));\n  std::cout << MP_UNITS_STD_FMT::format(\"- Planck constant:                      {} = {::N[.8e]}\\n\",\n                                        1. * si2019::planck_constant, (1. * si2019::planck_constant).in(J * s));\n  std::cout << MP_UNITS_STD_FMT::format(\"- elementary charge:                    {} = {::N[.9e]}\\n\",\n                                        1. * si2019::elementary_charge, (1. * si2019::elementary_charge).in(C));\n  std::cout << MP_UNITS_STD_FMT::format(\"- Boltzmann constant:                   {} = {::N[.6e]}\\n\",\n                                        1. * si2019::boltzmann_constant, (1. * si2019::boltzmann_constant).in(J / K));\n  std::cout << MP_UNITS_STD_FMT::format(\"- Avogadro constant:                    {} = {::N[.8e]}\\n\",\n                                        1. * si2019::avogadro_constant, (1. * si2019::avogadro_constant).in(one / mol));\n  std::cout << MP_UNITS_STD_FMT::format(\"- luminous efficacy:                    {} = {}\\n\",\n                                        1. * si2019::luminous_efficacy, (1. * si2019::luminous_efficacy).in(lm / W));\n}\n

    While analyzing the output of this program (provided below), we can easily notice that a direct printing of the quantity provides just a value 1 with a proper constant symbol. This is the main power of the Faster-than-lightspeed Constants feature. Only after we explicitly convert the unit of a quantity to proper SI units we get an actual numeric value of the constant.

    The seven defining constants of the SI and the seven corresponding units they define:\n- hyperfine transition frequency of Cs: 1 \u0394\u03bd_Cs = 9192631770 Hz\n- speed of light in vacuum:             1 c = 299792458 m/s\n- Planck constant:                      1 h = 6.62607015e-34 J s\n- elementary charge:                    1 e = 1.602176634e-19 C\n- Boltzmann constant:                   1 k = 1.380649e-23 J/K\n- Avogadro constant:                    1 N_A = 6.02214076e+23 1/mol\n- luminous efficacy:                    1 K_cd = 683 lm/W\n
    ","tags":["Physical Constants","Text Formatting"]},{"location":"users_guide/examples/tags_index/","title":"Tags Index","text":"

    Note

    mp-units usage example applications are meant to be built on all of the supported compilers. This is why they benefit from the Wide Compatibility mode.

    Tip

    All usage examples in this chapter are categorized with appropriate tags to simplify navigation and search of relevant code. You can either read all the examples one-by-one in the order provided by the documentation authors or, thanks to the tagging system, jump straight to the example that is the most interesting for you.

    "},{"location":"users_guide/examples/tags_index/#tag:affine-space","title":"Affine Space","text":""},{"location":"users_guide/examples/tags_index/#tag:cgs-system","title":"CGS System","text":""},{"location":"users_guide/examples/tags_index/#tag:embedded","title":"Embedded","text":""},{"location":"users_guide/examples/tags_index/#tag:international-system","title":"International System","text":""},{"location":"users_guide/examples/tags_index/#tag:physical-constants","title":"Physical Constants","text":""},{"location":"users_guide/examples/tags_index/#tag:text-formatting","title":"Text Formatting","text":""},{"location":"users_guide/framework_basics/character_of_a_quantity/","title":"Character of a Quantity","text":"

    Warning

    This chapter's features are experimental and subject to change or removal. Please share your feedback if something seems wrong or could be improved.

    "},{"location":"users_guide/framework_basics/character_of_a_quantity/#scalars-vectors-and-tensors","title":"Scalars, vectors, and tensors","text":"

    ISO 80000-2

    Scalars, vectors and tensors are mathematical objects that can be used to denote certain physical quantities and their values. They are as such independent of the particular choice of a coordinate system, whereas each scalar component of a vector or a tensor and each component vector and component tensor depend on that choice.

    Such distinction is important because each quantity character represents different properties and allows different operations to be done on its quantities.

    For example, imagine a physical units library that allows the creation of a \\(speed\\) quantity from both \\(length / time\\) and \\(length * time\\). It wouldn't be too safe to use such a product, right?

    Now we have to realize that both of the above operations (multiplication and division) are not even mathematically defined for linear algebra types such as vectors or tensors. On the other hand, two vectors can be passed as arguments to dot and cross-product operations. The result of the first one is a scalar. The second one results in a vector that is perpendicular to both vectors passed as arguments. Again, it wouldn't be safe to allow replacing those two operations with each other or expect the same results from both cases. This simply can't work.

    "},{"location":"users_guide/framework_basics/character_of_a_quantity/#isq-defines-quantities-of-all-characters","title":"ISQ defines quantities of all characters","text":"

    While defining quantities ISO 80000 explicitly mentions when a specific quantity has a vector or tensor character. Here are some examples:

    Quantity Character Quantity Equation \\(duration\\) scalar {base quantity} \\(mass\\) scalar {base quantity} \\(length\\) scalar {base quantity} \\(path\\; length\\) scalar {base quantity} \\(radius\\) scalar {base quantity} \\(position\\; vector\\) vector {base quantity} \\(velocity\\) vector \\(position\\; vector / duration\\) \\(acceleration\\) vector \\(velocity / duration\\) \\(force\\) vector \\(mass * acceleration\\) \\(power\\) scalar \\(force \\cdot velocity\\) \\(moment\\; of\\; force\\) vector \\(position\\; vector \\times force\\) \\(torque\\) scalar \\(moment\\; of\\; force \\cdot \\{unit\\; vector\\}\\) \\(surface\\; tension\\) scalar \\(\\lvert force \\rvert / length\\) \\(angular\\; displacement\\) scalar \\(path\\; length / radius\\) \\(angular\\; velocity\\) vector \\(angular\\; displacement / duration * \\{unit\\; vector\\}\\) \\(momentum\\) vector \\(mass * velocity\\) \\(angular\\; momentum\\) vector \\(position\\; vector \\times momentum\\) \\(moment\\; of\\; inertia\\) tensor \\(angular\\; momentum \\otimes angular\\; velocity\\)

    In the above equations:

    Note

    As of now, all of the C++ physical units libraries on the market besides mp-units do not support the operations mentioned above. They expose only multiplication and division operators, which do not work for linear algebra-based representation types. If a user of those libraries would like to create the quantities provided in the above table properly, this would result in a compile-time error stating that multiplication and division of two linear algebra vectors is impossible.

    "},{"location":"users_guide/framework_basics/character_of_a_quantity/#characters-dont-apply-to-dimensions-and-units","title":"Characters don't apply to dimensions and units","text":"

    ISO 80000 explicitly states that dimensions are orthogonal to quantity characters:

    ISO 80000-1:2009

    In deriving the dimension of a quantity, no account is taken of its scalar, vector, or tensor character.

    Also, it explicitly states that:

    ISO 80000-2

    All units are scalars.

    "},{"location":"users_guide/framework_basics/character_of_a_quantity/#defining-vector-and-tensor-quantities","title":"Defining vector and tensor quantities","text":"

    To specify that a specific quantity has a vector or tensor character a value of quantity_character enumeration can be appended to the quantity_spec describing such a quantity type:

    C++23C++20Portable 
    inline constexpr struct displacement final : quantity_spec<length, quantity_character::vector> {} displacement;\ninline constexpr struct position_vector final : quantity_spec<displacement> {} position_vector;\n
    inline constexpr struct displacement final : quantity_spec<displacement, length, quantity_character::vector> {} displacement;\ninline constexpr struct position_vector final : quantity_spec<position_vector, displacement> {} position_vector;\n
    QUANTITY_SPEC(displacement, length, quantity_character::vector);\nQUANTITY_SPEC(position_vector, displacement);\n

    With the above, all the quantities derived from position_vector or displacement will have a correct character determined according to the kind of operations included in the quantity equation defining a derived quantity.

    For example, velocity in the below definition will be defined as a vector quantity (no explicit character override is needed):

    C++23C++20Portable 
    inline constexpr struct velocity final : quantity_spec<speed, displacement / duration> {} velocity;\n
    inline constexpr struct velocity final : quantity_spec<velocity, speed, displacement / duration> {} velocity;\n
    QUANTITY_SPEC(velocity, speed, displacement / duration);\n
    "},{"location":"users_guide/framework_basics/character_of_a_quantity/#representation-types-for-vector-and-tensor-quantities","title":"Representation types for vector and tensor quantities","text":"

    As we remember, the quantity class template is defined as follows:

    template<Reference auto R,\n         RepresentationOf<get_quantity_spec(R)> Rep = double>\nclass quantity;\n

    The second template parameter is constrained with a RepresentationOf concept that checks if the provided representation type satisfies the requirements for the character associated with this quantity type.

    Note

    The current version of the C++ Standard Library does not provide any types that could be used as a representation type for vector and tensor quantities. This is why users are on their own here .

    To provide examples and implement unit tests, our library uses the types proposed in the P1385 and available as a Conan package in the Conan Center. However, thanks to the provided customization points, any linear algebra library types can be used as a vector or tensor quantity representation type.

    For example, here is how it can be done for the P1385 types:

    #include <matrix>\n\nusing la_vector = STD_LA::fixed_size_column_vector<double, 3>;\n\nQuantity auto q = la_vector{1, 2, 3} * isq::velocity[m / s];\n

    In case there is an ambiguity of operator* between mp-units and a linear algebra library, we can either:

    Note

    The following does not work:

    Quantity auto q1 = la_vector{1, 2, 3} * m / s;\nQuantity auto q2 = isq::velocity(la_vector{1, 2, 3} * m / s);\nquantity<isq::velocity[m/s]> q3{la_vector{1, 2, 3} * m / s};\n

    In all the cases above, the SI unit m / s has an associated scalar quantity of isq::length / isq::time. la_vector is not a correct representation type for a scalar quantity so the construction fails.

    "},{"location":"users_guide/framework_basics/concepts/","title":"Concepts","text":"

    This chapter enumerates all the user-facing concepts in the mp-units library.

    "},{"location":"users_guide/framework_basics/concepts/#Dimension","title":"Dimension<T>","text":"

    Dimension concept matches a dimension of either a base or derived quantity:

    All of the above dimensions have to be marked as final.

    "},{"location":"users_guide/framework_basics/concepts/#DimensionOf","title":"DimensionOf<T, V>","text":"

    DimensionOf concept is satisfied when both arguments satisfy a Dimension concept and when they compare equal.

    "},{"location":"users_guide/framework_basics/concepts/#QuantitySpec","title":"QuantitySpec<T>","text":"

    QuantitySpec concept matches all the quantity specifications including:

    All of the above quantity specifications have to be marked as final.

    "},{"location":"users_guide/framework_basics/concepts/#QuantitySpecOf","title":"QuantitySpecOf<T, V>","text":"

    QuantitySpecOf concept is satisfied when both arguments satisfy a QuantitySpec concept and when T is implicitly convertible to V.

    "},{"location":"users_guide/framework_basics/concepts/#UnitMagnitude","title":"UnitMagnitude<T>","text":"

    UnitMagnitude concept is satisfied by all types defining a unit magnitude.

    Info

    Unit magnitude implementation is a private implementation detail of the library.

    "},{"location":"users_guide/framework_basics/concepts/#Unit","title":"Unit<T>","text":"

    Unit concept matches all the units in the library including:

    All of the above units have to be marked as final.

    Note

    In the mp-units library, physical constants are also implemented as units.

    "},{"location":"users_guide/framework_basics/concepts/#AssociatedUnit","title":"AssociatedUnit<T>","text":"

    AssociatedUnit concept describes a unit with an associated quantity and is satisfied by:

    Examples

    All units in the SI have associated quantities. For example, si::second is specified to measure isq::time.

    Natural units typically do not have an associated quantity. For example, if we assume c = 1, a natural::second unit can be used to measure both time and length. In such case, speed would have a unit of one.

    "},{"location":"users_guide/framework_basics/concepts/#PrefixableUnit","title":"PrefixableUnit<T>","text":"

    PrefixableUnit concept is satisfied by all units derived from a named_unit class template. Such units can be passed as an argument to a prefixed_unit class template.

    "},{"location":"users_guide/framework_basics/concepts/#UnitOf","title":"UnitOf<T, V>","text":"

    UnitOf concept is satisfied for all units T for which an associated quantity spec is implicitly convertible to the provided QuantitySpec value.

    "},{"location":"users_guide/framework_basics/concepts/#Reference","title":"Reference<T>","text":"

    Reference concept is satisfied by all quantity reference types. Such types provide all the meta-information required to create a Quantity. A Reference can either be:

    "},{"location":"users_guide/framework_basics/concepts/#ReferenceOf","title":"ReferenceOf<T, V>","text":"

    ReferenceOf concept is satisfied by references T which have a quantity specification that satisfies QuantitySpecOf<V> concept.

    "},{"location":"users_guide/framework_basics/concepts/#RepresentationOf","title":"RepresentationOf<T, V>","text":"

    RepresentationOf concept constraints a type of a number that stores the value of a quantity and is satisfied:

    "},{"location":"users_guide/framework_basics/concepts/#Quantity","title":"Quantity<T>","text":"

    Quantity concept matches every quantity in the library and is satisfied by all types being or deriving from an instantiation of a quantity class template.

    "},{"location":"users_guide/framework_basics/concepts/#QuantityOf","title":"QuantityOf<T, V>","text":"

    QuantityOf concept is satisfied by all the quantities for which a ReferenceOf<V> is true.

    "},{"location":"users_guide/framework_basics/concepts/#QuantityLike","title":"QuantityLike<T>","text":"

    QuantityLike concept provides interoperability with other libraries and is satisfied by a type T for which an instantiation of quantity_like_traits type trait yields a valid type that provides:

    Examples

    This is how support for std::chrono::seconds can be provided:

    template<>\nstruct mp_units::quantity_like_traits<std::chrono::seconds> {\n  static constexpr auto reference = si::second;\n  static constexpr bool explicit_import = false;\n  static constexpr bool explicit_export = false;\n  using rep = std::chrono::seconds::rep;\n\n  [[nodiscard]] static constexpr rep to_numerical_value(const std::chrono::seconds& d)\n  {\n    return d.count();\n  }\n\n  [[nodiscard]] static constexpr std::chrono::seconds from_numerical_value(const rep& v)\n  {\n    return std::chrono::seconds(v);\n  }\n};\n\nquantity q = 42s;\nstd::chrono::seconds dur = 42 * s;\n
    "},{"location":"users_guide/framework_basics/concepts/#PointOrigin","title":"PointOrigin<T>","text":"

    PointOrigin concept matches all quantity point origins in the library. It is satisfied by either:

    "},{"location":"users_guide/framework_basics/concepts/#PointOriginFor","title":"PointOriginFor<T, V>","text":"

    PointOriginFor concept is satisfied by all PointOrigin types that have quantity type implicitly convertible from quantity specification V, which means that V must satisfy QuantitySpecOf<T::quantity_spec>.

    Examples

    si::ice_point can serve as a point origin for points of isq::Celsius_temperature because this quantity type implicitly converts to isq::thermodynamic_temperature.

    However, if we define mean_sea_level in the following way:

    inline constexpr struct mean_sea_level final : absolute_point_origin<isq::altitude> {} mean_sea_level;\n

    then it can't be used as a point origin for points of isq::length or isq::width as none of them is implicitly convertible to isq::altitude:

    "},{"location":"users_guide/framework_basics/concepts/#QuantityPoint","title":"QuantityPoint<T>","text":"

    QuantityPoint concept is satisfied by all types being either a specialization or derived from quantity_point class template.

    "},{"location":"users_guide/framework_basics/concepts/#QuantityPointOf","title":"QuantityPointOf<T, V>","text":"

    QuantityPointOf concept is satisfied by all the quantity points T that match the following value V:

    V Condition QuantitySpec The quantity point quantity specification satisfies ReferenceOf<V> concept. PointOrigin The point and V have the same absolute point origin."},{"location":"users_guide/framework_basics/concepts/#QuantityPointLike","title":"QuantityPointLike<T>","text":"

    QuantityPointLike concept provides interoperability with other libraries and is satisfied by a type T for which an instantiation of quantity_point_like_traits type trait yields a valid type that provides:

    Examples

    This is how support for a std::chrono::time_point of std::chrono::seconds can be provided:

    template<typename C>\nstruct mp_units::quantity_point_like_traits<std::chrono::time_point<C, std::chrono::seconds>> {\n  static constexpr auto reference = si::second;\n  static constexpr struct point_origin_ final : absolute_point_origin<isq::time> {} point_origin{};\n  static constexpr bool explicit_import = false;\n  static constexpr bool explicit_export = false;\n  using rep = std::chrono::seconds::rep;\n  using T = std::chrono::time_point<C, std::chrono::seconds>;\n\n  [[nodiscard]] static constexpr rep to_numerical_value(const T& tp)\n  {\n    return tp.time_since_epoch().count();\n  }\n\n  [[nodiscard]] static constexpr T from_numerical_value(const rep& v)\n  {\n    return T(std::chrono::seconds(v));\n  }\n};\n\nquantity_point qp = time_point_cast<std::chrono::seconds>(std::chrono::system_clock::now());\nstd::chrono::sys_seconds q = qp + 42 * s;\n
    "},{"location":"users_guide/framework_basics/design_overview/","title":"Design Overview","text":"

    The most important entities in the mp-units library are:

    The graph provided below presents how those and a few other entities depend on each other:

    flowchart TD\n    Unit --- Reference\n    Dimension --- QuantitySpec[\"Quantity specification\"]\n    quantity_character[\"Quantity character\"] --- QuantitySpec\n    QuantitySpec --- Reference[\"Quantity reference\"]\n    Reference --- Quantity\n    quantity_character -.- Representation\n    Representation --- Quantity\n    Quantity --- QuantityPoint[\"Quantity point\"]\n    PointOrigin[\"Point origin\"] --- QuantityPoint\n\n    click Dimension \"#dimension\"\n    click quantity_character \"#quantity-character\"\n    click QuantitySpec \"#quantity-specification\"\n    click Unit \"#unit\"\n    click Reference \"#quantity-reference\"\n    click Representation \"#quantity-representation\"\n    click Quantity \"#quantity\"\n    click PointOrigin \"#point-origin\"\n    click QuantityPoint \"#quantity-point\"
    "},{"location":"users_guide/framework_basics/design_overview/#dimension","title":"Dimension","text":"

    Dimension specifies the dependence of a quantity on the base quantities of a particular system of quantities. It is represented as a product of powers of factors corresponding to the base quantities, omitting any numerical factor.

    In the mp-units library, we use the terms:

    For example:

    Base dimensions can be defined by the user in the following way:

    inline constexpr struct dim_length final : base_dimension<\"L\"> {} dim_length;\ninline constexpr struct dim_time final : base_dimension<\"T\"> {} dim_time;\n

    Derived dimensions are implicitly created by the library's framework based on the quantity equation provided in the quantity specification:

    C++23C++20Portable 
    inline constexpr struct length final : quantity_spec<dim_length> {} length;\ninline constexpr struct time final : quantity_spec<dim_time> {} time;\ninline constexpr struct speed final : quantity_spec<length / time> {} speed;\n\nstatic_assert(speed.dimension == dim_length / dim_time);\n
    inline constexpr struct length final : quantity_spec<length, dim_length> {} length;\ninline constexpr struct time final : quantity_spec<time, dim_time> {} time;\ninline constexpr struct speed final : quantity_spec<speed, length / time> {} speed;\n\nstatic_assert(speed.dimension == dim_length / dim_time);\n
    QUANTITY_SPEC(length, dim_length);\nQUANTITY_SPEC(time, dim_time);\nQUANTITY_SPEC(speed, length / time);\n\nstatic_assert(speed.dimension == dim_length / dim_time);\n

    Important

    Users should not explicitly define any derived dimensions. Those should always be implicitly created by the framework.

    The multiplication/division on quantity specifications also multiplies/divides their dimensions:

    static_assert((length / time).dimension == dim_length / dim_time);\n

    The dimension equation of isq::dim_length / isq::dim_time results in the derived_dimension<isq::dim_length, per<isq::dim_time>> type.

    "},{"location":"users_guide/framework_basics/design_overview/#quantity-character","title":"Quantity character","text":"

    ISO 80000 explicitly states that quantities (even of the same kind) may have different characters:

    The quantity character in the mp-units library is implemented with the quantity_character enumeration:

    enum class quantity_character { real_scalar, complex_scalar, vector, tensor };\n

    Info

    You can read more on quantity characters in the \"Character of a Quantity\" chapter.

    "},{"location":"users_guide/framework_basics/design_overview/#quantity-specification","title":"Quantity specification","text":"

    Dimension is not enough to describe a quantity. This is why the ISO 80000 provides hundreds of named quantity types. It turns out that there are many more quantity types in the ISQ than the named units in the SI.

    This is why the mp-units library introduces a quantity specification entity that stores:

    Note

    We know that it might be sometimes confusing to talk about quantities, quantity types/names, and quantity specifications. However, it might be important to notice here that even the ISO 80000 admits that:

    It is customary to use the same term, \"quantity\", to refer to both general quantities, such as length, mass, etc., and their instances, such as given lengths, given masses, etc. Accordingly, we are used to saying both that length is a quantity and that a given length is a quantity by maintaining the specification \u2013 \"general quantity, \\(Q\\)\" or \"individual quantity, \\(Q_\\textsf{a}\\)\" \u2013 implicit and exploiting the linguistic context to remove the ambiguity.

    In the mp-units library, we have a:

    For example:

    Quantity specification can be defined by the user in one of the following ways:

    C++23C++20Portable 
    inline constexpr struct length final : quantity_spec<dim_length> {} length;\ninline constexpr struct height final : quantity_spec<length> {} height;\ninline constexpr struct speed final : quantity_spec<length / time> {} speed;\n
    inline constexpr struct length final : quantity_spec<length, dim_length> {} length;\ninline constexpr struct height final : quantity_spec<height, length> {} height;\ninline constexpr struct speed final : quantity_spec<speed, length / time> {} speed;\n
    QUANTITY_SPEC(length, dim_length);\nQUANTITY_SPEC(height, length);\nQUANTITY_SPEC(speed, length / time);\n

    The quantity equation of isq::length / isq::time results in the derived_quantity_spec<isq::length, per<isq::time>> type.

    "},{"location":"users_guide/framework_basics/design_overview/#unit","title":"Unit","text":"

    A unit is a concrete amount of a quantity that allows us to measure the values of quantities of the same kind and represent the result as a number being the ratio of the two quantities.

    For example:

    Note

    In the mp-units library, physical constants are also implemented as units.

    A unit can be defined by the user in one of the following ways:

    template<PrefixableUnit U> struct kilo_ : prefixed_unit<\"k\", mag_power<10, 3>, U{}> {};\ntemplate<PrefixableUnit auto U> constexpr kilo_<decltype(U)> kilo;\n\ninline constexpr struct second final : named_unit<\"s\", kind_of<isq::time>> {} second;\ninline constexpr struct minute final : named_unit<\"min\", mag<60> * second> {} minute;\ninline constexpr struct gram   final : named_unit<\"g\", kind_of<isq::mass>> {} gram;\ninline constexpr auto kilogram = kilo<gram>;\ninline constexpr struct newton final : named_unit<\"N\", kilogram * metre / square(second)> {} newton;\n\ninline constexpr struct speed_of_light_in_vacuum final : named_unit<\"c\", mag<299'792'458> * metre / second> {} speed_of_light_in_vacuum;\n

    The unit equation of si::metre / si::second results in the derived_unit<si::metre, per<si::second>> type.

    "},{"location":"users_guide/framework_basics/design_overview/#quantity-reference","title":"Quantity reference","text":"

    ISO defines a quantity as:

    Quote

    property of a phenomenon, body, or substance, where the property has a magnitude that can be expressed as a number and a reference

    After that, it says:

    Quote

    A reference can be a measurement unit, a measurement procedure, a reference material, or a combination of such.

    In the mp-units library, a quantity reference provides all the domain-specific metadata for the quantity besides its numerical value:

    Together with the value of a representation type, it forms a quantity.

    In the library, we have two different ways to provide a reference:

    Note

    All the units of the SI have associated quantity kinds and may serve as a reference.

    For example:

    "},{"location":"users_guide/framework_basics/design_overview/#quantity-representation","title":"Quantity representation","text":"

    Quantity representation defines the type used to store the numerical value of a quantity. Such a type should be of a specific quantity character provided in the quantity specification.

    Note

    By default, all floating-point and integral (besides bool) types are treated as scalars.

    "},{"location":"users_guide/framework_basics/design_overview/#quantity","title":"Quantity","text":"

    ISO defines a quantity as:

    Quote

    property of a phenomenon, body, or substance, where the property has a magnitude that can be expressed as a number and a reference

    This is why a quantity class template is defined in the library as:

    template<Reference auto R,\n         RepresentationOf<get_quantity_spec(R)> Rep = double>\nclass quantity;\n

    Its value can be easily created by multiplying/dividing the numerical value and a reference.

    For example:

    "},{"location":"users_guide/framework_basics/design_overview/#point-origin","title":"Point origin","text":"

    In the affine space theory, the point origin specifies where the \"zero\" of our measurement's scale is.

    In the mp-units library, we have two types of point origins:

    For example:

    inline constexpr struct absolute_zero final : absolute_point_origin<isq::thermodynamic_temperature> {} absolute_zero;\n
    inline constexpr struct ice_point final : relative_point_origin<absolute_zero + 273'150 * milli<kelvin>> {} ice_point;\n
    "},{"location":"users_guide/framework_basics/design_overview/#quantity-point","title":"Quantity point","text":"

    Quantity point implements a point in the affine space theory.

    In the mp-units library, the quantity point is implemented as:

    template<Reference auto R,\n         PointOriginFor<get_quantity_spec(R)> auto PO,\n         RepresentationOf<get_quantity_spec(R)> Rep = double>\nclass quantity_point;\n

    Its value can be easily created by adding/subtracting the quantity with a point origin.

    For example:

    constexpr auto room_reference_temperature = ice_point + delta<isq::Celsius_temperature[deg_C]>(21);\n
    "},{"location":"users_guide/framework_basics/dimensionless_quantities/","title":"Dimensionless Quantities","text":"

    The quantities we discussed so far always had some specific type and physical dimension. However, this is not always the case. While performing various computations, we sometimes end up with so-called \"dimensionless\" quantities, which ISO defines as quantities of dimension one:

    ISO/IEC Guide 99

    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#dividing-two-quantities-of-the-same-kind","title":"Dividing two quantities of the same kind","text":"

    Dividing two quantities of the same kind always results in a quantity of dimension one. However, depending on what type of quantities we divide or what their units are, we may end up with slightly different results.

    Note

    In mp-units, dividing two quantities of the same dimension always results in a quantity with the dimension being dimension_one. This is often different for other physical units libraries, which may return a raw representation type for such cases. A raw value is also always returned from the division of two std::chrono::duration objects.

    To read more about the reasoning for this design decision, please check our FAQ.

    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#dividing-quantities-of-the-same-type","title":"Dividing quantities of the same type","text":"

    First, let's analyze what happens if we divide two quantities of the same type:

    constexpr QuantityOf<dimensionless> auto q = isq::height(200 * m) / isq::height(50 * m);\n

    In such a case, we end up with a dimensionless quantity that has the following properties:

    static_assert(q.quantity_spec == dimensionless);\nstatic_assert(q.dimension == dimension_one);\nstatic_assert(q.unit == one);\n

    In case we would like to print its value, we would see a raw value of 4 in the output with no unit being printed.

    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#dividing-quantities-of-different-types","title":"Dividing quantities of different types","text":"

    Now let's see what happens if we divide quantities of the same dimension and unit but which have different quantity types:

    constexpr QuantityOf<dimensionless> auto q = isq::work(200 * J) / isq::heat(50 * J);\n

    Again we end up with dimension_one and one, but this time:

    static_assert(q.quantity_spec == isq::work / isq::heat);\n

    As shown above, the result is not of a dimensionless type anymore. Instead, we get a quantity type derived from the performed quantity equation. According to the ISQ, work divided by heat is the recipe for the thermodynamic efficiency quantity, thus:

    static_assert(implicitly_convertible(q.quantity_spec, isq::efficiency_thermodynamics));\n

    Note

    The quantity of isq::efficiency_thermodynamics is of a kind dimensionless, so it is implicitly convertible to dimensionless and satisfies the QuantityOf<dimensionless> concept.

    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#dividing-quantities-of-different-units","title":"Dividing quantities of different units","text":"

    Now, let's see what happens when we divide two quantities of the same type but different units:

    constexpr QuantityOf<dimensionless> auto q = isq::height(4 * km) / isq::height(2 * m);\n

    This time, we still get a quantity of the dimensionless type with a dimension_one as its dimension. However, the resulting unit is not one anymore:

    static_assert(q.unit == mag_power<10, 3> * one);\n

    In case we would print the text output of this quantity, we would not see a raw value of 2000, but 2 km/m.

    First, it may look surprising, but this is consistent with dividing quantities of different dimensions. For example, if we divide 4 * km / 2 * s, we do not expect km to be \"expanded\" to m before the division, right? We would expect the result of 2 km/s, which is exactly what we get when we divide quantities of the same kind.

    This is a compelling feature that allows us to express huge or tiny ratios without the need for big and expensive representation types. With this, we can easily define things like a Hubble's constant that uses a unit that is proportional to the ratio of kilometers per megaparsecs, which are both units of length:

    inline constexpr struct hubble_constant final :\n    named_unit<{u8\"H\u2080\", \"H_0\"}, mag_ratio<701, 10> * si::kilo<si::metre> / si::second / si::mega<parsec>> {} hubble_constant;\n
    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#counts-of-things","title":"Counts of things","text":"

    Another important use case for dimensionless quantities is to provide strong types for counts of things. For example:

    Thanks to assigning strong names to such quantities, later on, they can be explicitly used as arguments in the quantity equations of other quantities deriving from them.

    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#predefined-units-of-the-dimensionless-quantity","title":"Predefined units of the dimensionless quantity","text":"

    As we observed above, the most common unit for dimensionless quantities is one. It has the ratio of 1 and does not output any textual symbol.

    Important: one is an identity

    A unit one is special in the entire type system of units as it is considered to be an identity operand in the unit symbolic expressions. This means that, for example:

    static_assert(one * one == one);\nstatic_assert(one * si::metre == si::metre);\nstatic_assert(si::metre / si::metre == one);\n

    The same is also true for dimension_one and dimensionless in the domains of dimensions and quantity specifications.

    Besides the unit one, there are a few other scaled units predefined in the library for usage with dimensionless quantities:

    inline constexpr struct percent final : named_unit<\"%\", mag_ratio<1, 100> * one> {} percent;\ninline constexpr struct per_mille final : named_unit<{u8\"\u2030\", \"%o\"}, mag_ratio<1, 1000> * one> {} per_mille;\ninline constexpr struct parts_per_million final : named_unit<\"ppm\", mag_ratio<1, 1'000'000> * one> {} parts_per_million;\ninline constexpr auto ppm = parts_per_million;\n
    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#superpowers-of-the-unit-one","title":"Superpowers of the unit one","text":"

    Quantities implicitly convertible to dimensionless with the unit equivalent to one are the only ones that are:

    quantity<one> inc(quantity<one> q) { return q + 1; }\nvoid legacy(double) { /* ... */ }\n\nif (auto q = inc(42); q != 0)\n  legacy(static_cast<int>(q));\n

    This property also expands to usual arithmetic operators.

    Note

    Those rules do not apply to all the dimensionless quantities. It would be unsafe and misleading to allow such operations on units with a magnitude different than 1 (e.g., percent) or for quantities that are not implicitly convertible to dimensionless (e.g., angular_measure).

    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#angular-quantities","title":"Angular quantities","text":"

    Special, often controversial, examples of dimensionless quantities are an angular measure and solid angular measure quantities that are defined in the ISQ to be the result of a division of \\(arc\\; length / radius\\) and \\(area / radius^2\\) respectively. Moreover, ISQ also explicitly states that both can be expressed in the unit one. This means that both angular measure and solid angular measure should be of a kind dimensionless.

    On the other hand, ISQ also specifies that a unit radian can be used for angular measure, and a unit steradian can be used for solid angular measure. Those should not be mixed or used to express other types of dimensionless quantities. This means that both angular measure and solid angular measure should also be quantity kinds by themselves.

    Note

    Many people claim that angle being a dimensionless quantity is a bad idea. There are proposals submitted to make an angle a base quantity and rad to become a base unit. More on this topic can be found in the \"Strong Angular System\" chapter.

    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#radians-and-degrees-support","title":"Radians and degrees support","text":"

    Thanks to the usage of magnitudes the library provides efficient strong types for all angular types. This means that with the built-in support for magnitudes of \\(\\pi\\) we can provide accurate conversions between radians and degrees. The library also provides common trigonometric functions for angular quantities:

    using namespace mp_units::si::unit_symbols;\nusing mp_units::angular::unit_symbols::rad;\nusing mp_units::angular::unit_symbols::deg;\nusing mp_units::angular::unit_symbols::grad;\n\nquantity speed = 110 * km / h;\nquantity rate_of_climb = -0.63657 * m / s;\nquantity glide_ratio = speed / -rate_of_climb;\nquantity glide_angle = angular::asin(1 / glide_ratio);\n\nstd::println(\"Glide ratio: {::N[.1f]}\", glide_ratio.in(one));\nstd::println(\"Glide angle:\");\nstd::println(\" - {::N[.4f]}\", glide_angle.in(rad));\nstd::println(\" - {::N[.2f]}\", glide_angle.in(deg));\nstd::println(\" - {::N[.2f]}\", glide_angle.in(grad));\n

    The above program prints:

    Glide ratio: 48.0\nGlide angle:\n - 0.0208 rad\n - 1.19\u00b0\n - 1.33\u1d4d\n

    Note

    In the production code the above speed and rate_of_climb quantities should probably be modelled as separate typed quantities of the same kind.

    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#nested-quantity-kinds","title":"Nested quantity kinds","text":"

    Angular quantities are not the only ones with such a \"strange\" behavior. Another but a similar case is a storage capacity quantity specified in IEC-80000-13 that again allows expressing it in both one and bit units.

    Those cases make dimensionless quantities an exceptional tree in the library. This quantity hierarchy contains more than one quantity kind and more than one unit in its tree:

    flowchart TD\n    dimensionless[\"<b>dimensionless</b><br>[one]\"]\n    dimensionless --- rotation[\"<b>rotation</b>\"]\n    dimensionless --- thermodynamic_efficiency[\"<b>thermodynamic_efficiency</b><br><i>(work / heat)</i>\"]\n    dimensionless --- angular_measure[\"<b>angular_measure</b><br><i>(arc_length / radius)</i><br>[rad]\"]\n    angular_measure --- rotational_displacement[\"<b>rotational_displacement</b><br><i>(path_length / radius)</i>\"]\n    angular_measure --- phase_angle[\"<b>phase_angle</b>\"]\n    dimensionless --- solid_angular_measure[\"<b>solid_angular_measure</b><br><i>(area / pow<2>(radius))</i><br>[sr]\"]\n    dimensionless --- drag_factor[\"<b>drag_factor</b><br><i>(drag_force / (mass_density * pow<2>(speed) * area))</i>\"]\n    dimensionless --- storage_capacity[\"<b>storage_capacity</b><br>[bit]\"] --- equivalent_binary_storage_capacity[\"<b>equivalent_binary_storage_capacity</b>\"]\n    dimensionless --- ...

    To provide such support in the library, we provided an is_kind specifier that can be appended to the quantity specification:

    C++23C++20Portable 
    inline constexpr struct angular_measure final : quantity_spec<dimensionless, arc_length / radius, is_kind> {} angular_measure;\ninline constexpr struct solid_angular_measure final : quantity_spec<dimensionless, area / pow<2>(radius), is_kind> {} solid_angular_measure;\ninline constexpr struct storage_capacity final : quantity_spec<dimensionless, is_kind> {} storage_capacity;\n
    inline constexpr struct angular_measure final : quantity_spec<angular_measure, dimensionless, arc_length / radius, is_kind> {} angular_measure;\ninline constexpr struct solid_angular_measure final : quantity_spec<solid_angular_measure, dimensionless, area / pow<2>(radius), is_kind> {} solid_angular_measure;\ninline constexpr struct storage_capacity final : quantity_spec<storage_capacity, dimensionless, is_kind> {} storage_capacity;\n
    QUANTITY_SPEC(angular_measure, dimensionless, arc_length / radius, is_kind);\nQUANTITY_SPEC(solid_angular_measure, dimensionless, area / pow<2>(radius), is_kind);\nQUANTITY_SPEC(storage_capacity, dimensionless, is_kind);\n

    With the above, we can constrain radian, steradian, and bit to be allowed for usage with specific quantity kinds only:

    inline constexpr struct radian final : named_unit<\"rad\", metre / metre, kind_of<isq::angular_measure>> {} radian;\ninline constexpr struct steradian final : named_unit<\"sr\", square(metre) / square(metre), kind_of<isq::solid_angular_measure>> {} steradian;\ninline constexpr struct bit final : named_unit<\"bit\", one, kind_of<storage_capacity>> {} bit;\n

    but still allow the usage of one and its scaled versions for such quantities.

    Info

    It is worth mentioning here that converting up the hierarchy beyond a subkind requires an explicit conversion. For example:

    static_assert(implicitly_convertible(isq::rotation, dimensionless));\nstatic_assert(!implicitly_convertible(isq::angular_measure, dimensionless));\nstatic_assert(explicitly_convertible(isq::angular_measure, dimensionless));\n

    This increases type safety and prevents accidental quantities with invalid units. For example, a result of a conversion from isq::angular_measure[rad] to dimensionless would be a reference of dimensionless[rad], which contains an incorrect unit for a dimensionless quantity. Such a conversion must be explicit and be preceded by an explicit unit conversion:

    quantity q1 = isq::angular_measure(42. * rad);\nquantity<dimensionless[one]> q2 = dimensionless(q1.in(one));\n
    "},{"location":"users_guide/framework_basics/faster_than_lightspeed_constants/","title":"Faster-than-lightspeed Constants","text":"

    In most libraries, physical constants are implemented as constant (possibly constexpr) quantity values. Such an approach has some disadvantages, often affecting the run time performance and causing a loss of precision.

    "},{"location":"users_guide/framework_basics/faster_than_lightspeed_constants/#simplifying-constants-in-an-equation","title":"Simplifying constants in an equation","text":"

    When dealing with equations involving physical constants, they often occur more than once in an expression. Such a constant may appear both in a numerator and denominator of a quantity equation. As we know from fundamental physics, we can simplify such an expression by striking a constant out of the equation. Supporting such behavior allows a faster runtime performance and often a better precision of the resulting value.

    "},{"location":"users_guide/framework_basics/faster_than_lightspeed_constants/#physical-constants-as-units","title":"Physical constants as units","text":"

    The mp-units library allows and encourages the implementation of physical constants as regular units. With that, the constant's value is handled at compile-time, and under favorable circumstances, it can be simplified in the same way as all other repeated units do. If it is not simplified, the value is stored in a type, and the expensive multiplication or division operations can be delayed in time until a user selects a specific unit to represent/print the data.

    Such a feature often also allows using simpler or faster representation types in the equation. For example, instead of always having to multiply a small integral value with a big floating-point constant number, we can just use the integral type all the way. Only in case a constant will not simplify in the equation, and the user will require a specific unit, such a multiplication will be lazily invoked, and the representation type will need to be expanded to facilitate that. With that, addition, subtractions, multiplications, and divisions will always be the fastest - compiled away or done in out-of-order execution.

    To benefit from all of the above, in the mp-units library, SI defining and other constants are implemented as units in the following way:

    namespace si {\n\nnamespace si2019 {\n\ninline constexpr struct speed_of_light_in_vacuum final :\n  named_unit<\"c\", mag<299'792'458> * metre / second> {} speed_of_light_in_vacuum;\n\n}  // namespace si2019\n\ninline constexpr struct magnetic_constant final :\n  named_unit<{u8\"\u03bc\u2080\", \"u_0\"}, mag<4> * mag<\u03c0> * mag_power<10, -7> * henry / metre> {} magnetic_constant;\n\n}  // namespace mp_units::si\n
    "},{"location":"users_guide/framework_basics/faster_than_lightspeed_constants/#usage-examples","title":"Usage examples","text":"

    With the above definitions, we can calculate vacuum permittivity as:

    constexpr auto permeability_of_vacuum = 1. * si::magnetic_constant;\nconstexpr auto speed_of_light_in_vacuum = 1 * si::si2019::speed_of_light_in_vacuum;\n\nQuantityOf<isq::permittivity_of_vacuum> auto q = 1 / (permeability_of_vacuum * pow<2>(speed_of_light_in_vacuum));\n\nstd::println(\"permittivity of vacuum = {} = {::N[.3e]}\", q, q.in(F / m));\n

    The above first prints the following:

    permittivity of vacuum = 1  \u03bc\u2080\u207b\u00b9 c\u207b\u00b2 = 8.854e-12 F/m\n

    As we can clearly see, all the calculations above were just about multiplying and dividing the number 1 with the rest of the information provided as a compile-time type. Only when a user wants a specific SI unit as a result, the unit ratios are lazily resolved.

    Another similar example can be an equation for total energy:

    QuantityOf<isq::mechanical_energy> auto total_energy(QuantityOf<isq::momentum> auto p,\n                                                     QuantityOf<isq::mass> auto m,\n                                                     QuantityOf<isq::speed> auto c)\n{\n  return isq::mechanical_energy(sqrt(pow<2>(p * c) + pow<2>(m * pow<2>(c))));\n}\n
    constexpr auto GeV = si::giga<si::electronvolt>;\nconstexpr QuantityOf<isq::speed> auto c = 1. * si::si2019::speed_of_light_in_vacuum;\nconstexpr auto c2 = pow<2>(c);\n\nconst auto p1 = isq::momentum(4. * GeV / c);\nconst QuantityOf<isq::mass> auto m1 = 3. * GeV / c2;\nconst auto E = total_energy(p1, m1, c);\n\nstd::cout << \"in `GeV` and `c`:\\n\"\n          << \"p = \" << p1 << \"\\n\"\n          << \"m = \" << m1 << \"\\n\"\n          << \"E = \" << E << \"\\n\";\n\nconst auto p2 = p1.in(GeV / (m / s));\nconst auto m2 = m1.in(GeV / pow<2>(m / s));\nconst auto E2 = total_energy(p2, m2, c).in(GeV);\n\nstd::cout << \"\\nin `GeV`:\\n\"\n          << \"p = \" << p2 << \"\\n\"\n          << \"m = \" << m2 << \"\\n\"\n          << \"E = \" << E2 << \"\\n\";\n\nconst auto p3 = p1.in(kg * m / s);\nconst auto m3 = m1.in(kg);\nconst auto E3 = total_energy(p3, m3, c).in(J);\n\nstd::cout << \"\\nin SI base units:\\n\"\n          << \"p = \" << p3 << \"\\n\"\n          << \"m = \" << m3 << \"\\n\"\n          << \"E = \" << E3 << \"\\n\";\n

    The above prints the following:

    in `GeV` and `c`:\np = 4 GeV/c\nm = 3 GeV/c\u00b2\nE = 5 GeV\n\nin `GeV`:\np = 1.33426e-08 GeV s/m\nm = 3.33795e-17 GeV s\u00b2/m\u00b2\nE = 5 GeV\n\nin SI base units:\np = 2.13771e-18 kg m/s\nm = 5.34799e-27 kg\nE = 8.01088e-10 J\n
    "},{"location":"users_guide/framework_basics/generic_interfaces/","title":"Generic Interfaces","text":"

    Using a concrete unit in the interface often makes a lot of sense. It is especially useful if we store the data internally in the object. In such a case, we have to select a specific unit anyway.

    For example, let's consider a simple storage tank:

    class StorageTank {\n  quantity<horizontal_area[m2]> base_;\n  quantity<isq::height[m]> height_;\n  quantity<isq::mass_density[kg / m3]> density_ = air_density;\npublic:\n  constexpr StorageTank(const quantity<horizontal_area[m2]>& base, const quantity<isq::height[m]>& height) :\n      base_(base), height_(height)\n  {\n  }\n\n  // ...\n};\n

    As the quantities provided in the function's interface are then stored in the class, there is probably no sense in using generic interfaces here.

    "},{"location":"users_guide/framework_basics/generic_interfaces/#the-issues-with-unit-specific-interfaces","title":"The issues with unit-specific interfaces","text":"

    However, in many cases, using a specific unit in the interface is counterproductive. Let's consider the following function:

    quantity<km / h> avg_speed(quantity<km> distance, quantity<h> duration)\n{\n  return distance / duration;\n}\n

    Everything seems fine for now. It also works great if we call it with:

    quantity<km / h> s1 = avg_speed(220 * km, 2 * h);\n

    However, if the user starts doing the following:

    quantity<mi / h> s2 = avg_speed(140 * mi, 2 * h);\nquantity<m / s> s3 = avg_speed(20 * m, 2 * s);\n

    some issues start to be clearly visible:

    1. The arguments must be converted to units mandated by the function's parameters at each call. This involves potentially expensive multiplication/division operations at runtime.
    2. After the function returns the speed in a unit of km/h, another potentially expensive multiplication/division operations must be performed to convert the resulting quantity into a unit being the derived unit of the initial function's arguments.
    3. Besides the obvious runtime cost, some unit conversions may result in a value truncation, which means that the result will not be exactly equal to a direct division of the function's arguments.

    4. We have to use a floating-point representation type (the quantity class template by default uses double as a representation type) which is considered value-preserving. Trying to use an integral type in this scenario will work only for s1, while s2 and s3 will fail to compile. Failing to compile is a good thing here as the library tries to prevent the user from doing a clearly wrong thing. To make the code compile, the user needs to use dedicated value_cast or force_in like this:

      quantity<isq::speed[mi / h]> s2 = avg_speed(value_cast<km>(140 * mi), 2 * h);\nquantity<isq::speed[m / s]> s3 = avg_speed((20 * m).force_in(km), (2 * s).force_in(h));\n

      but the above will obviously provide an incorrect behavior (e.g., division by 0 in the evaluation of s3).

    "},{"location":"users_guide/framework_basics/generic_interfaces/#a-naive-solution","title":"A naive solution","text":"

    A naive solution here would be to implement the function as an unconstrained function template:

    auto avg_speed(auto distance, auto duration)\n{\n  return distance / duration;\n}\n

    Beware, this is not a good solution. The above code is too generic. Such a function template accepts everything:

    Note

    The usage of auto instead of a function parameter type is a C++20 feature. It makes such a code a function template where the type of such a parameter will be deduced during the template instantiation process from the argument type passed by the user.

    "},{"location":"users_guide/framework_basics/generic_interfaces/#constraining-function-template-arguments-with-concepts","title":"Constraining function template arguments with concepts","text":"

    Much better generic code can be implemented using basic concepts provided with the library:

    Original template notationThe shorthand notationTerse notation 
    template<typename Distance, typename Duration>\n  requires QuantityOf<Distance, isq::length> && QuantityOf<Duration, isq::time>\nauto avg_speed(Distance distance, Duration duration)\n{\n  return isq::speed(distance / duration);\n}\n
    template<QuantityOf<isq::length> Distance, QuantityOf<isq::time> Duration>\nauto avg_speed(Distance distance, Duration duration)\n{\n  return isq::speed(distance / duration);\n}\n
    auto avg_speed(QuantityOf<isq::length> auto distance,\n               QuantityOf<isq::time> auto duration)\n{\n  return isq::speed(distance / duration);\n}\n

    This explicitly states that the arguments passed by the user must not only satisfy a Quantity concept, but also their quantity specification must be implicitly convertible to isq::length and isq::time accordingly. This no longer leaves room for error while still allowing the compiler to generate the most efficient code.

    Tip

    Please note that now it is safe just to use integral types all the way which again improves the runtime performance as the multiplication/division operations are often faster on the integral rather than floating-point types.

    "},{"location":"users_guide/framework_basics/generic_interfaces/#constraining-function-template-return-type","title":"Constraining function template return type","text":"

    The above function template resolves all of the issues described before. However, we can do even better here by additionally constraining the return type:

    QuantityOf<isq::speed> auto avg_speed(QuantityOf<isq::length> auto distance,\n                                      QuantityOf<isq::time> auto duration)\n{\n  return isq::speed(distance / duration);\n}\n

    Doing so has two important benefits:

    1. It informs the users of our interface about what to expect to be the result of a function invocation. It is superior to just returning auto, which does not provide any hint about the thing being returned there.
    2. Such a concept constrains the type returned from the function. This means that it works as a unit test to verify if our function actually performs what it is supposed to do. If there is an error in quantity equations, we will learn about it right away.
    "},{"location":"users_guide/framework_basics/generic_interfaces/#constraining-a-variable-on-the-stack","title":"Constraining a variable on the stack","text":"

    If we know precisely what the function does in its internals and if we know the exact argument types passed to such a function, we often know the exact type that will be returned from its invocation.

    However, if we care about performance, we should often use the generic interfaces described in this chapter. A side effect is that we sometimes are unsure about the return type. Even if we know it today, it might change a week from now due to some code refactoring.

    In such cases, we can again use auto to denote the type:

    auto s1 = avg_speed(220 * km, 2 * h);\nauto s2 = avg_speed(140 * mi, 2 * h);\nauto s3 = avg_speed(20 * m, 2 * s);\n

    or benefit from CTAD:

    quantity s1 = avg_speed(220 * km, 2 * h);\nquantity s2 = avg_speed(140 * mi, 2 * h);\nquantity s3 = avg_speed(20 * m, 2 * s);\n

    In both cases, it is probably OK to do so as the avg_speed function name explicitly provides the information on what to expect as a result.

    In other scenarios where the returned quantity type is not so obvious, it is again helpful to constrain the type with a concept like so:

    QuantityOf<isq::speed> auto s1 = avg_speed(220 * km, 2 * h);\nQuantityOf<isq::speed> auto s2 = avg_speed(140 * mi, 2 * h);\nQuantityOf<isq::speed> auto s3 = avg_speed(20 * m, 2 * s);\n

    The above explicitly provides additional information about the quantity we are dealing with in the code, and it serves as a unit test checking if the \"thing\" returned from a function is actually what we expected here.

    Note

    The QuantityOf and QuantityPointOf concepts are probably the most useful, but there are a few more to play with. A list of all the concepts can be found in the Basic Concepts chapter.

    "},{"location":"users_guide/framework_basics/interface_introduction/","title":"Interface Introduction","text":""},{"location":"users_guide/framework_basics/interface_introduction/#new-style-of-definitions","title":"New style of definitions","text":"

    The mp-units library decided to use a rather unusual pattern to define entities. Here is how we define metre and second SI base units:

    inline constexpr struct metre final : named_unit<\"m\", kind_of<isq::length>> {} metre;\ninline constexpr struct second final : named_unit<\"s\", kind_of<isq::time>> {} second;\n

    Please note that the above reuses the same identifier for a type and its value. The rationale behind this is that:

    Important

    To improve compiler errors' readability and make it easier to correlate them with a user's written code, a new idiom in the library is to use the same identifier for a type and its instance.

    Also, to prevent possible issues in compile-time logic, all of the library's entities must be marked final. This prevents the users to derive own strong types from them, which would prevent symbolic expressions simplification of equivalent entities.

    "},{"location":"users_guide/framework_basics/interface_introduction/#strong-types-instead-of-aliases","title":"Strong types instead of aliases","text":"

    Let's look again at the above units definitions. Another important point to notice is that all the types describing entities in the library are short, nicely named identifiers that derive from longer, more verbose class template instantiations. This is really important to improve the user experience while debugging the program or analyzing the compilation error.

    Note

    Such a practice is rare in the industry. Some popular C++ physical units libraries generate enormously long error messages where even only the first line failed to fit on a slide with a tiny font.

    "},{"location":"users_guide/framework_basics/interface_introduction/#entities-composability","title":"Entities composability","text":"

    Many physical units libraries (in C++ or any other programming language) assign strong types to library entities (e.g., derived units). While metre_per_second as a type may not look too scary, consider, for example, units of angular momentum. If we followed this path, its coherent unit would look like kilogram_metre_sq_per_second. Now, consider how many scaled versions of this unit you would predefine in the library to ensure that all users are happy with your choice? How expensive would it be from the implementation point of view? What about potential future standardization efforts?

    This is why in mp-units, we put a strong requirement to make everything as composable as possible. For example, to create a quantity with a unit of speed, one may write:

    quantity<si::metre / si::second> q;\n

    In case we use such a unit often and would prefer to have a handy helper for it, we can always do something like this:

    constexpr auto metre_per_second = si::metre / si::second;\nquantity<metre_per_second> q;\n

    or choose any shorter identifier of our choice.

    Coming back to the angular momentum case, thanks to the composability of units, a user can create such a quantity in the following way:

    using namespace mp_units::si::unit_symbols;\nauto q = la_vector{1, 2, 3} * isq::angular_momentum[kg * m2 / s];\n

    It is a much better solution. It is terse and easy to understand. Please also notice how easy it is to obtain any scaled version of such a unit (e.g., mg * square(mm) / min) without having to introduce hundreds of types to predefine them.

    "},{"location":"users_guide/framework_basics/interface_introduction/#value-based-equations","title":"Value-based equations","text":"

    The mp-units library is based on C++20, significantly improving user experience. One of such improvements is the usage of value-based equations.

    As we have learned above, the entities are being used as values in the code, and they compose. Moreover, derived entities can be defined in the library using such value-based equations. This is a huge improvement compared to what we can find in other physical units libraries or what we have to deal with when we want to write some equations for std::ratio.

    For example, below are a few definitions of the SI derived units showing the power of C++20 extensions to Non-Type Template Parameters, which allow us to directly pass a result of the value-based unit equation to a class template definition:

    inline constexpr struct newton final : named_unit<\"N\", kilogram * metre / square(second)> {} newton;\ninline constexpr struct pascal final : named_unit<\"Pa\", newton / square(metre)> {} pascal;\ninline constexpr struct joule  final : named_unit<\"J\", newton * metre> {} joule;\n
    "},{"location":"users_guide/framework_basics/interface_introduction/#symbolic-expressions","title":"Symbolic expressions","text":"

    The previous chapter provided a rationale for not having predefined types for derived entities. In many libraries, such an approach results in long and unreadable compilation errors, as framework-generated types are typically far from being easy to read and understand.

    The mp-units library greatly improves the user experience by extensively using symbolic expressions. Such expressions are used consistently throughout the entire library to describe the results of:

    For example, if we take the above-defined base units and put the results of their division into the quantity class template like this:

    quantity<metre / second> q;\n

    we will observe the following type in the debugger

    (gdb) ptype q\ntype = class mp_units::quantity<mp_units::derived_unit<metre, mp_units::per<second>>(), double> [with Rep = double] {\n

    The same type identifier will be visible in the compilation error (in case it happens).

    Important

    Expressions templates are extensively used throughout the library to improve the readability of the resulting types.

    "},{"location":"users_guide/framework_basics/interface_introduction/#identities","title":"Identities","text":"

    As mentioned above, equations can be performed on dimensions, quantities, and units. Each such domain must introduce an identity object that can be used in the resulting expressions. Here is the list of identities used in the library:

    Domain Concept Identity Dimension dimension_one QuantitySpec dimensionless Unit one

    In the equations, a user can explicitly refer to an identity object. For example:

    constexpr auto my_unit = one / second;\n

    Note

    Another way to achieve the same result is to call an inverse() function:

    constexpr auto my_unit = inverse(second);\n

    Both cases will result in the same symbolic expression being generated and put into the wrapper class template.

    "},{"location":"users_guide/framework_basics/interface_introduction/#supported-operations-and-their-results","title":"Supported operations and their results","text":"

    There are only a few operations that one can do on such entities, and the result of each of them has its unique representation in the library:

    Operation Resulting template expression arguments A * B A, B B * A A, B A * A power<A, 2> {identity} * A A A * {identity} A A / B A, per<B> A / A {identity} A / {identity} A {identity} / A {identity}, per<A> pow<2>(A) power<A, 2> pow<2>({identity}) {identity} sqrt(A) or pow<1, 2>(A) power<A, 1, 2> sqrt({identity}) or pow<1, 2>({identity}) {identity}"},{"location":"users_guide/framework_basics/interface_introduction/#simplifying-the-resulting-symbolic-expressions","title":"Simplifying the resulting symbolic expressions","text":"

    To limit the length and improve the readability of generated types, there are many rules to simplify the resulting symbolic expression.

    1. Ordering

      The resulting comma-separated arguments of multiplication are always sorted according to a specific predicate. This is why:

      static_assert(A * B == B * A);\nstatic_assert(std::is_same_v<decltype(A * B), decltype(B * A)>);\n

      This is probably the most important of all the steps, as it allows comparing types and enables the rest of the simplification rules.

    2. Aggregation

      In case two of the same identifiers are found next to each other on the argument list they will be aggregated in one entry:

      Before After A, A power<A, 2> A, power<A, 2> power<A, 3> power<A, 1, 2>, power<A, 2> power<A, 5, 2> power<A, 1, 2>, power<A, 1, 2> A

    3. Simplification

      In case two of the same identifiers are found in the numerator and denominator argument lists; they are being simplified into one entry:

      Before After A, per<A> {identity} power<A, 2>, per<A> A power<A, 3>, per<A> power<A, 2> A, per<power<A, 2>> {identity}, per<A>

      It is important to notice here that only the elements with exactly the same type are being simplified. This means that, for example, m/m results in one, but km/m will not be simplified. The resulting derived unit will preserve both symbols and their relative magnitude. This allows us to properly print symbols of some units or constants that require such behavior. For example, the Hubble constant is expressed in km\u22c5s\u207b\u00b9\u22c5Mpc\u207b\u00b9, where both km and Mpc are units of length.

      Also, to prevent possible issues in compile-time logic, all of the library's entities must be marked final. This prevents the users to derive own strong types from them, which would prevent symbolic expression simplification of equivalent entities.

    4. Repacking

      In case an expression uses two results of other operations, the components of its arguments are repacked into one resulting type and simplified there.

      For example, assuming:

      constexpr auto X = A / B;\n

      then:

      Operation Resulting template expression arguments X * B A X * A power<A, 2>, per<B> X * X power<A, 2>, per<power<B, 2>> X / X {identity} X / A {identity}, per<B> X / B A, per<power<B, 2>>
    "},{"location":"users_guide/framework_basics/interface_introduction/#example","title":"Example","text":"

    Thanks to all of the features described above, a user may write the code like this one:

    using namespace mp_units::si::unit_symbols;\nquantity speed = 60. * isq::speed[km / h];\nquantity duration = 8 * s;\nquantity acceleration = speed / duration;\nstd::cout << \"acceleration: \" << acceleration << \" (\" << acceleration.in(m / s2) << \")\\n\";\n

    The acceleration quantity, being the result of the above code, has the following type (after stripping the mp_units namespace for brevity):

    quantity<reference<derived_quantity_spec<isq::speed, per<isq::time>>{}, derived_unit<si::kilo_<si::metre{}>, per<non_si::hour, si::second>>{}>{}, int>\n

    and the text output presents:

    acceleration: 7.5 km h\u207b\u00b9 s\u207b\u00b9 (2.08333 m/s\u00b2)\n
    "},{"location":"users_guide/framework_basics/obtaining_metadata/","title":"Obtaining Metadata","text":""},{"location":"users_guide/framework_basics/obtaining_metadata/#quantity-spec","title":"quantity spec","text":""},{"location":"users_guide/framework_basics/obtaining_metadata/#unit","title":"unit","text":""},{"location":"users_guide/framework_basics/obtaining_metadata/#reference","title":"reference","text":""},{"location":"users_guide/framework_basics/obtaining_metadata/#quantity","title":"quantity","text":""},{"location":"users_guide/framework_basics/quantity_arithmetics/","title":"Quantity Arithmetics","text":""},{"location":"users_guide/framework_basics/quantity_arithmetics/#quantity-is-a-numeric-wrapper","title":"quantity is a numeric wrapper","text":"

    If we think about it, the quantity class template is just a \"smart\" numeric wrapper. It exposes properly constrained set of arithmetic operations on one or two operands.

    Important: quantity propagates the underlying interface

    Every single arithmetic operator is exposed by the quantity class template only if the underlying representation type provides it as well, and when its implementation has proper semantics (e.g., returns a reasonable type).

    For example, in the following code, -a will compile only if MyInt exposes such an operation as well:

    quantity a = MyInt{42} * m;\nquantity b = -a;\n

    Assuming that:

    here is the list of all the supported operators:

    As we can see, there are plenty of operations one can do on a value of a quantity type. As most of them are obvious, in the following chapters, we will discuss only the most important or non-trivial aspects of quantity arithmetics.

    "},{"location":"users_guide/framework_basics/quantity_arithmetics/#addition-and-subtraction","title":"Addition and subtraction","text":"

    Quantities can easily be added or subtracted from each other:

    static_assert(1 * m + 1 * m == 2 * m);\nstatic_assert(2 * m - 1 * m == 1 * m);\nstatic_assert(isq::height(1 * m) + isq::height(1 * m) == isq::height(2 * m));\nstatic_assert(isq::height(2 * m) - isq::height(1 * m) == isq::height(1 * m));\n

    The above uses the same types for LHS, RHS, and the result, but in general, we can add, subtract, or compare the values of any quantity type as long as both quantities are of the same kind. The result of such an operation will be the common type of the arguments:

    static_assert(1 * km + 1.5 * m == 1001.5 * m);\nstatic_assert(isq::height(1 * m) + isq::width(1 * m) == isq::length(2 * m));\nstatic_assert(isq::height(2 * m) - isq::distance(0.5 * m) == 1.5 * m);\nstatic_assert(isq::radius(1 * m) - 0.5 * m == isq::radius(0.5 * m));\n

    Note

    Please note that for the compound assignment operators, we always need to end up with the left-hand-side argument type:

    static_assert((1 * m += 1 * km) == 1001 * m);\nstatic_assert((isq::length(1 * m) += isq::height(1 * m)) == isq::length(1 * m));\nstatic_assert((isq::height(1.5 * m) -= 1 * m) == isq::height(0.5 * m));\n

    If we will break typical library's convertibility rules, the following code will not compile:

    quantity q1 = 1 * m -= 0.5 * m;                         // Compile-time error(1)\nquantity q2 = 1 * km += 1 * m;                          // Compile-time error(2)\nquantity q3 = isq::height(1 * m) += isq::length(1 * m); // Compile-time error(3)\n
    1. Conversion of the floating-point to integral representation type is considered narrowing.
    2. Conversion of quantity with integral representation type from a unit of a higher resolution to the one with a lower resolution is considered narrowing.
    3. Conversion from a more generic quantity type to a more specific one is considered unsafe.
    "},{"location":"users_guide/framework_basics/quantity_arithmetics/#multiplication-and-division","title":"Multiplication and division","text":"

    Multiplying or dividing a quantity by a number does not change its quantity type or unit. However, its representation type may change. For example:

    static_assert(isq::height(3 * m) * 0.5 == isq::height(1.5 * m));\n

    Note

    Unless we use a compound assignment operator, in which case we always have to result with the type of the left-hand-side argument. This, together with the fact that this library tries to prevent truncation of a quantity value means, that the following does not compile:

    quantity q = isq::height(3 * m) *= 0.5; // Compile-time error\n

    However, suppose we multiply or divide quantities of the same or different types or we divide a raw number by a quantity. In that case, we most probably will end up in a quantity of yet another type:

    static_assert(120 * km / (2 * h) == 60 * km / h);\nstatic_assert(isq::width(2 * m) * isq::length(2 * m) == isq::area(4 * m2));\nstatic_assert(50 / isq::time(1 * s) == isq::frequency(50 * Hz));\n

    Note

    An exception from the above rule happens when one of the arguments is a dimensionless quantity. If we multiply or divide by such a quantity, the quantity type will not change. If such a quantity has a unit one, also the unit of a quantity will not change:

    static_assert(120 * m / (2 * one) == 60 * m);\n

    An interesting special case happens when we divide the same quantity kinds or multiply a quantity by its inverted type. In such a case, we end up with a dimensionless quantity.

    static_assert(isq::height(4 * m) / isq::width(2 * m) == 2 * one); // (1)!\nstatic_assert(5 * h / (120 * min) == 0 * one);  // (2)!\nstatic_assert(5. * h / (120 * min) == 2.5 * one);\n
    1. The resulting quantity type of the LHS is isq::height / isq::width, which is a quantity of the dimensionless kind.
    2. The resulting quantity of the LHS is 0 * dimensionless[h / min]. To be consistent with the division of different quantity types, we do not convert quantity values to a common unit before the division.

    Important: Beware of integral division

    The physical units library can't do any runtime branching logic for the division operator. All logic must be done at compile-time when the actual values are unknown, and the quantity types can't change at runtime.

    If we expect 120 * km / (2 * h) to return 60 km / h, we have to agree with the fact that 5 * km / (24 * h) returns 0 km/h. We can't do a range check at runtime to dynamically adjust scales and types based on the values of provided function arguments.

    This is why we often prefer floating-point representation types when dealing with units. Some popular physical units libraries even forbid integer division at all.

    "},{"location":"users_guide/framework_basics/quantity_arithmetics/#modulo","title":"Modulo","text":"

    Now that we know how addition, subtraction, multiplication, and division work, it is time to discuss modulo. What would we expect to be returned from the following quantity equation?

    auto q = 5 * h % (120 * min);\n

    Most of us would probably expect to see 1 h or 60 min as a result. And this is where the problems start.

    C++ language defines its / and % operators with the quotient-remainder theorem:

    q = a / b;\nr = a % b;\nq * b + r == a;\n

    The important property of the modulo operation is that it only works for integral representation types (it is undefined what modulo for floating-point types means). However, as we saw in the previous chapter, integral types are tricky because they often truncate the value.

    From the quotient-remainder theorem, the result of modulo operation is r = a - q * b. Let's see what we get from such a quantity equation on integral representation types:

    const quantity a = 5 * h;\nconst quantity b = 120 * min;\nconst quantity q = a / b;\nconst quantity r = a - q * b;\n\nstd::cout << \"reminder: \" << r << \"\\n\";\n

    The above code outputs:

    reminder: 5 h\n

    And now, a tough question needs an answer. Do we really want modulo operation on physical units to be consistent with the quotient-remainder theorem and return 5 h for 5 * h % (120 * min)?

    This is exactly why we decided not to follow this hugely surprising path in the mp-units library. The selected approach was also consistent with the feedback from the C++ experts. For example, this is what Richard Smith said about this issue:

    Richard Smith

    I think the quotient-remainder property is a less important motivation here than other factors -- the constraints on % and / are quite different, so they lack the inherent connection they have for integers. In particular, I would expect that A / B works for all quantities A and B, whereas A % B is only meaningful when A and B have the same dimension. It seems like a nice-to-have for the property to apply in the case where both / and % are defined, but internal consistency of / across all cases seems much more important to me.

    I would expect 61 min % 1 h to be 1 min, and 1 h % 59 min to also be 1 min, so my intuition tells me that the result type of A % B, where A and B have the same dimension, should have the smaller unit of A and B (and if the smaller one doesn't divide the larger one, we should either use the gcd / std::common_type of the units of A and B or perhaps just produce an error). I think any other behavior for % is hard to defend.

    On the other hand, for division it seems to me that the choice of unit should probably not affect the result, and so if we want that 5 mm / 120 min = 0 mm/min, then 5 h / 120 min == 0 hc (where hc is a dimensionless \"hexaconta\", or 60x, unit). I don't like the idea of taking SI base units into account; that seems arbitrary and like it would do the wrong thing as often as it does the right thing, especially when the units have a multiplier that is very large or small. We could special-case the situation of a dimensionless quantity, but that could lead to problematic overflow pretty easily: a calculation such as 10 s * 5 GHz * 2 uW would overflow an int if it produces a dimensionless quantity for 10 s * 5 GHz, but it could equally produce 50 G * 2 uW = 100 kW without any overflow, and presumably would if the terms were merely reordered.

    If people want to use integer-valued quantities, I think it's fundamental that you need to know what the units of the result of an operation will be, and take that into account in how you express computations; the simplest rule for heterogeneous operators like * or / seems to be that the units of the result are determined by applying the operator to the units of the operands -- and for homogeneous operators like + or %, it seems like the only reasonable option is that you get the std::common_type of the units of the operands.

    To summarize, the modulo operation on physical units has more in common with addition and division operators than with the quotient-remainder theorem. To avoid surprising results, the operation uses a common unit to do the calculation and provide its result:

    static_assert(5 * h / (120 * min) == 0 * one);\nstatic_assert(5 * h % (120 * min) == 60 * min);\nstatic_assert(61 * min % (1 * h) == 1 * min);\nstatic_assert(1 * h % (59 * min) == 1 * min);\n
    "},{"location":"users_guide/framework_basics/quantity_arithmetics/#comparison-against-zero","title":"Comparison against zero","text":"

    In our code, we often want to compare the value of a quantity against zero. For example, we do it every time we want to ensure that we deal with a non-zero or positive value.

    We could implement such checks in the following way:

    if (q1 / q2 != 0 * m / s)\n  // ...\n

    The above would work (assuming we are dealing with the quantity of speed) but could be suboptimal if the result of q1 / q2 is not expressed in m / s. To eliminate the need for conversion, we need to write:

    if (auto q = q1 / q2; q != q.zero())\n  // ...\n

    but that is a bit inconvenient, and inexperienced users could be unaware of this technique and its reasons.

    For the above reasons, the library provides dedicated interfaces to compare against zero that follow the naming convention of named comparison functions in the C++ Standard Library. The mp-units/compare.h header file exposes the following functions:

    Thanks to them, to save typing and not pay for unneeded conversions, our check could be implemented as follows:

    if (is_neq_zero(q1 / q2))\n  // ...\n

    Tip

    Those functions will work with any type T that exposes zero() member function returning something comparable to T. Thanks to that, we can use them not only with quantities but also with std::chrono::duration or any other type that exposes such an interface.

    "},{"location":"users_guide/framework_basics/quantity_arithmetics/#other-maths","title":"Other maths","text":"

    This chapter scopes only on the quantity type's operators. However, there are many named math functions taking quantities as arguments. Those can be found in the mp-units/math.h header file. Among others, we can find there the following:

    In the library, we can also find mp-units/random.h header file with all the pseudo-random number generators working on quantity types.

    "},{"location":"users_guide/framework_basics/simple_and_typed_quantities/","title":"Simple and Typed Quantities","text":"

    ISO defines a quantity as:

    Quote

    property of a phenomenon, body, or substance, where the property has a magnitude that can be expressed as a number and a reference

    After that, it says:

    Quote

    A reference can be a measurement unit, a measurement procedure, a reference material, or a combination of such.

    "},{"location":"users_guide/framework_basics/simple_and_typed_quantities/#quantity-class-template","title":"quantity class template","text":"

    In the mp-units library, a quantity is represented with the following class template:

    template<Reference auto R,\n         RepresentationOf<get_quantity_spec(R)> Rep = double>\nclass quantity;\n

    The concept Reference is satisfied by a type that provides all the domain-specific metadata describing a quantity (besides the representation type and its value). Such a type can be either:

    Important

    All units in the SI system have an associated quantity type.

    A reference type is implicitly created as a result of the following expression:

    constexpr auto ref = isq::length[m];\n

    The above example results in the following type reference<isq::length(), si::metre()> being instantiated.

    As we have two alternative options that satisfy the Reference concept in the mp-units library, we also have two modes of dealing with quantities.

    "},{"location":"users_guide/framework_basics/simple_and_typed_quantities/#simple-quantities","title":"Simple quantities","text":"

    The simple mode might be preferred by many developers. It is all about units. Quantities using this mode have shorter type identifiers, resulting in easier-to-understand error messages and better debugging experience.

    Here is a simple example showing how to deal with such quantities:

    C++ modulesHeader files 
    #include <print>\nimport mp_units;\n\nusing namespace mp_units;\n\nconstexpr quantity<si::metre / si::second> avg_speed(quantity<si::metre> dist,\n                                                     quantity<si::second> time)\n{\n  return dist / time;\n}\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n\n  const quantity distance = 110 * km;\n  const quantity duration = 2 * h;\n  const quantity speed = avg_speed(distance, duration);\n\n  std::println(\"A car driving {} in {} has an average speed of {::N[.4]} ({::N[.4]})\",\n               distance, duration, speed, speed.in(km / h));\n}\n
    #include <mp-units/systems/si.h>\n#include <print>\n\nusing namespace mp_units;\n\nconstexpr quantity<si::metre / si::second> avg_speed(quantity<si::metre> dist,\n                                                     quantity<si::second> time)\n{\n  return dist / time;\n}\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n\n  const quantity distance = 110 * km;\n  const quantity duration = 2 * h;\n  const quantity speed = avg_speed(distance, duration);\n\n  std::println(\"A car driving {} in {} has an average speed of {::N[.4]} ({::N[.4]})\",\n               distance, duration, speed, speed.in(km / h));\n}\n

    The code above prints:

    A car driving 110 km in 2 h has an average speed of 15.28 m/s (55 km/h)\n

    Try it on Compiler Explorer

    "},{"location":"users_guide/framework_basics/simple_and_typed_quantities/#user-provided-unit-wrappers","title":"User-provided unit wrappers","text":"

    Sometimes it might be awkward to type some derived units:

    quantity speed = 60 * km / h;\n

    In case such a unit is used a lot in the project, a user can easily provide a nicely named wrapper for it with:

    constexpr auto kmph = km / h;\nquantity speed = 60 * kmph;\n
    "},{"location":"users_guide/framework_basics/simple_and_typed_quantities/#easy-to-understand-compilation-error-messages","title":"Easy-to-understand compilation error messages","text":"

    In case a user makes an error in a quantity equation and the result of the calculation will not match the function return type, the compiler will detect such an issue at compile-time.

    For example, in case we will make the following error:

    constexpr quantity<si::metre / si::second> avg_speed(quantity<si::metre> dist,\n                                                     quantity<si::second> time)\n{\n  return dist * time;  // (1)!\n}\n
    1. Quantities multiplied (instead of divided) by accident.

    the following compilation error message will be provided:

    error: no viable conversion from returned value of type\n       'quantity<mp_units::derived_unit<mp_units::si::metre, mp_units::si::second>{{{}}}, [...]>'\n       to function return type\n       'quantity<mp_units::derived_unit<mp_units::si::metre, mp_units::per<mp_units::si::second>>{{{}}}, [...]>'\n   10 |   return dist * time;\n      |          ^~~~~~~~~~~\n
    "},{"location":"users_guide/framework_basics/simple_and_typed_quantities/#typed-quantities","title":"Typed quantities","text":"

    Simple mode is all about and just about units. Typed quantities should be preferred if we also want to be quantity-safe. This, for example, allows us to specify if we deal with width, height, or radius and ensure we will not assign one to another by accident.

    The previous example can be re-typed using typed quantities in the following way:

    C++ modulesHeader files 
    #include <print>\nimport mp_units;\n\nusing namespace mp_units;\n\nconstexpr quantity<isq::speed[si::metre / si::second]> avg_speed(quantity<isq::length[si::metre]> dist,\n                                                                 quantity<isq::time[si::second]> time)\n{\n  return dist / time;\n}\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n\n  const quantity distance = isq::distance(110 * km);\n  const quantity duration = isq::time(2 * h);\n  const quantity speed = avg_speed(distance, duration);\n\n  std::println(\"A car driving {} in {} has an average speed of {::N[.4]} ({::N[.4]})\",\n               distance, duration, speed, speed.in(km / h));\n}\n
    #include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n#include <print>\n\nusing namespace mp_units;\n\nconstexpr quantity<isq::speed[si::metre / si::second]> avg_speed(quantity<isq::length[si::metre]> dist,\n                                                                 quantity<isq::time[si::second]> time)\n{\n  return dist / time;\n}\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n\n  const quantity distance = isq::distance(110 * km);\n  const quantity duration = isq::time(2 * h);\n  const quantity speed = avg_speed(distance, duration);\n\n  std::println(\"A car driving {} in {} has an average speed of {::N[.4]} ({::N[.4]})\",\n               distance, duration, speed, speed.in(km / h));\n}\n
    A car driving 110 km in 2 h has an average speed of 15.28 m/s (55 km/h)\n

    Try it on Compiler Explorer

    In case we will accidentally make the same calculation error as before, this time, we will get a bit longer error message, this time also containing information about the quantity type:

    error: no viable conversion from returned value of type\n       'quantity<reference<get_quantity_spec(metre{}) * struct time{{{}}}, metre{} * second{{}}>{}, [...]>'\n       to function return type\n       'quantity<reference<speed{}, derived_unit<metre, per<second>>{}>{}, [...]>'\n   12 |   return dist * time;\n      |          ^~~~~~~~~~~\n

    As we can see above, the compilation error is longer but still relatively easy to understand.

    "},{"location":"users_guide/framework_basics/simple_and_typed_quantities/#quantity-safety-with-typed-quantities","title":"Quantity-safety with typed quantities","text":"

    Based on the previous example, it might seem that typed quantities are not that useful, more to type and provide harder-to-understand error messages. It might be true in some cases, but there are scenarios where they offer additional level of safety.

    Let's see another example:

    C++ modulesHeader files SimpleTyped 
    #include <numbers>\nimport mp_units;\n\nusing namespace mp_units;\n\nclass StorageTank {\n  quantity<square(si::metre)> base_;\n  quantity<si::metre> height_;\npublic:\n  constexpr StorageTank(const quantity<square(si::metre)>& base,\n                        const quantity<si::metre>& height) :\n    base_(base), height_(height)\n  {\n  }\n\n  // ...\n};\n\nclass CylindricalStorageTank : public StorageTank {\npublic:\n  constexpr CylindricalStorageTank(const quantity<si::metre>& radius,\n                                   const quantity<si::metre>& height) :\n    StorageTank(std::numbers::pi * pow<2>(radius), height)\n  {\n  }\n};\n\nclass RectangularStorageTank : public StorageTank {\npublic:\n  constexpr RectangularStorageTank(const quantity<si::metre>& length,\n                                   const quantity<si::metre>& width,\n                                   const quantity<si::metre>& height) :\n    StorageTank(length * width, height)\n  {\n  }\n};\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n  auto tank = RectangularStorageTank(1'000 * mm, 500 * mm, 200 * mm);\n  // ...\n}\n
    #include <numbers>\nimport mp_units;\n\nusing namespace mp_units;\n\n// add a custom quantity type of kind isq::length\ninline constexpr struct horizontal_length final :\n    quantity_spec<isq::length> {} horizontal_length;\n\n// add a custom derived quantity type of kind isq::area\n// with a constrained quantity equation\ninline constexpr struct horizontal_area final :\n    quantity_spec<isq::area, horizontal_length * isq::width> {} horizontal_area;\n\nclass StorageTank {\n  quantity<horizontal_area[square(si::metre)]> base_;\n  quantity<isq::height[si::metre]> height_;\npublic:\n  constexpr StorageTank(const quantity<horizontal_area[square(si::metre)]>& base,\n                        const quantity<isq::height[si::metre]>& height) :\n    base_(base), height_(height)\n  {\n  }\n\n  // ...\n};\n\nclass CylindricalStorageTank : public StorageTank {\npublic:\n  constexpr CylindricalStorageTank(const quantity<isq::radius[si::metre]>& radius,\n                                   const quantity<isq::height[si::metre]>& height) :\n    StorageTank(quantity_cast<horizontal_area>(std::numbers::pi * pow<2>(radius)),\n                height)\n  {\n  }\n};\n\nclass RectangularStorageTank : public StorageTank {\npublic:\n  constexpr RectangularStorageTank(const quantity<horizontal_length[si::metre]>& length,\n                                   const quantity<isq::width[si::metre]>& width,\n                                   const quantity<isq::height[si::metre]>& height) :\n    StorageTank(length * width, height)\n  {\n  }\n};\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n  auto tank = RectangularStorageTank(horizontal_length(1'000 * mm),\n                                     isq::width(500 * mm),\n                                     isq::height(200 * mm));\n  // ...\n}\n
    SimpleTyped 
    #include <mp-units/math.h>\n#include <mp-units/systems/si.h>\n#include <numbers>\n\nusing namespace mp_units;\n\nclass StorageTank {\n  quantity<square(si::metre)> base_;\n  quantity<si::metre> height_;\npublic:\n  constexpr StorageTank(const quantity<square(si::metre)>& base,\n                        const quantity<si::metre>& height) :\n    base_(base), height_(height)\n  {\n  }\n\n  // ...\n};\n\nclass CylindricalStorageTank : public StorageTank {\npublic:\n  constexpr CylindricalStorageTank(const quantity<si::metre>& radius,\n                                   const quantity<si::metre>& height) :\n    StorageTank(std::numbers::pi * pow<2>(radius), height)\n  {\n  }\n};\n\nclass RectangularStorageTank : public StorageTank {\npublic:\n  constexpr RectangularStorageTank(const quantity<si::metre>& length,\n                                   const quantity<si::metre>& width,\n                                   const quantity<si::metre>& height) :\n    StorageTank(length * width, height)\n  {\n  }\n};\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n  auto tank = RectangularStorageTank(1'000 * mm, 500 * mm, 200 * mm);\n  // ...\n}\n
    #include <mp-units/math.h>\n#include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n#include <numbers>\n\nusing namespace mp_units;\n\n// add a custom quantity type of kind isq::length\ninline constexpr struct horizontal_length final :\n    quantity_spec<isq::length> {} horizontal_length;\n\n// add a custom derived quantity type of kind isq::area\n// with a constrained quantity equation\ninline constexpr struct horizontal_area final :\n    quantity_spec<isq::area, horizontal_length * isq::width> {} horizontal_area;\n\nclass StorageTank {\n  quantity<horizontal_area[square(si::metre)]> base_;\n  quantity<isq::height[si::metre]> height_;\npublic:\n  constexpr StorageTank(const quantity<horizontal_area[square(si::metre)]>& base,\n                        const quantity<isq::height[si::metre]>& height) :\n    base_(base), height_(height)\n  {\n  }\n\n  // ...\n};\n\nclass CylindricalStorageTank : public StorageTank {\npublic:\n  constexpr CylindricalStorageTank(const quantity<isq::radius[si::metre]>& radius,\n                                   const quantity<isq::height[si::metre]>& height) :\n    StorageTank(quantity_cast<horizontal_area>(std::numbers::pi * pow<2>(radius)),\n                height)\n  {\n  }\n};\n\nclass RectangularStorageTank : public StorageTank {\npublic:\n  constexpr RectangularStorageTank(const quantity<horizontal_length[si::metre]>& length,\n                                   const quantity<isq::width[si::metre]>& width,\n                                   const quantity<isq::height[si::metre]>& height) :\n    StorageTank(length * width, height)\n  {\n  }\n};\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n  auto tank = RectangularStorageTank(horizontal_length(1'000 * mm),\n                                     isq::width(500 * mm),\n                                     isq::height(200 * mm));\n  // ...\n}\n

    In the above example, the highlighted call doesn't look that safe anymore in the case of simple quantities, right? Suppose someone, either by mistake or due to some refactoring, will call the function with an invalid order of arguments. In that case, the program will compile fine but not work as expected.

    Let's see what will happen if we reorder the arguments in the case of typed quantities:

    auto tank = RectangularStorageTank(horizontal_length(1'000 * mm),\n                                   isq::height(200 * mm),\n                                   isq::width(500 * mm));\n

    This time, a compiler provides the following compilation error:

    <source>:53:15: error: no matching constructor for initialization of 'RectangularStorageTank'\n   53 |   auto tank = RectangularStorageTank(horizontal_length(1'000 * mm),\n      |               ^                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n   54 |                                      isq::height(200 * mm),\n      |                                      ~~~~~~~~~~~~~~~~~~~~~~\n   55 |                                      isq::width(500 * mm));\n      |                                      ~~~~~~~~~~~~~~~~~~~~\n<source>:43:13: note: candidate constructor not viable: no known conversion from\n                'quantity<mp_units::reference<mp_units::isq::height{{{{{}}}}},\n                                              mp_units::si::milli_<mp_units::si::metre{{}}>{{{{}}}}>{}, int>' to\n                'const quantity<reference<width{}, metre{}>{}, (default) double>' for 2nd argument\n   43 |   constexpr RectangularStorageTank(const quantity<horizontal_length[m]>& length,\n      |             ^\n   44 |                                    const quantity<isq::width[m]>& width,\n      |                                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n

    What about derived quantities? In the above example, you probably noticed that we also defined a custom horizontal_area quantity of kind isq::area. This quantity has the unique property of being implicitly constructible only from the result of the multiplication of quantities of horizontal_area and isq::width or the ones that implicitly convert to them.

    Based on the above error message, we already know that a quantity of isq::height is not implicitly constructible to the quantity of isq::width. This property is transitively passed to derived quantities using them. If by accident, we will try to create a StorageTank base class in the following way:

    class RectangularStorageTank : public StorageTank {\npublic:\n  constexpr RectangularStorageTank(const quantity<horizontal_length[m]>& length,\n                                   const quantity<isq::width[m]>& width,\n                                   const quantity<isq::height[m]>& height) :\n    StorageTank(length * height, height)\n  {\n  }\n};\n

    we will again get a compilation error message like this one:

    error: no matching constructor for initialization of 'StorageTank'\n   46 |     StorageTank(length * height, height)\n      |     ^           ~~~~~~~~~~~~~~~~~~~~~~~\n<source>:22:13: note: candidate constructor not viable: no known conversion from\n                'quantity<mp_units::reference<mp_units::derived_quantity_spec<horizontal_length, mp_units::isq::height>{{}, {{}}},\n                                              mp_units::derived_unit<mp_units::power<mp_units::si::metre, 2>>{{{}}}>{}, [...]>' to\n                'const quantity<reference<horizontal_area{}, derived_unit<power<metre, 2>>{}>{}, [...]>' for 1st argument\n   22 |   constexpr StorageTank(const quantity<horizontal_area[m2]>& base,\n      |             ^           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n

    Tip

    If you need to use various quantities of the same kind, consider using typed quantities to bring an additional level of safety to your project.

    "},{"location":"users_guide/framework_basics/simple_and_typed_quantities/#quantity_cast-to-force-unsafe-conversions","title":"quantity_cast() to force unsafe conversions","text":"

    Did you notice the quantity_cast() usage in the other child class?

    class CylindricalStorageTank : public StorageTank {\npublic:\n  constexpr CylindricalStorageTank(const quantity<isq::radius[m]>& radius,\n                                   const quantity<isq::height[m]>& height) :\n    StorageTank(quantity_cast<horizontal_area>(std::numbers::pi * pow<2>(radius)),\n                height)\n  {\n  }\n};\n

    As isq::radius is not convertible to horizontal_length, the derived quantity of pow<2>(radius) can't be converted to horizontal_area as well. It would be unsafe to allow such a conversion as not all of the circles lie flat on the ground, right?

    In such a case, the user has to explicitly force such an unsafe conversion with the help of a quantity_cast(). This function name is easy to spot in code reviews or while searching the project for problems if something goes sideways. In case of unexpected quantities-related issues, this should be the first function to look for.

    Tip

    Do not overuse quantity_cast(). Use it only when necessary and ensure that the requested conversion is exactly what you need in this case.

    "},{"location":"users_guide/framework_basics/simple_and_typed_quantities/#which-mode-should-i-use-in-my-project","title":"Which mode should I use in my project?","text":"

    We have good news for you if you wonder which mode you should choose for your project. Simple and typed quantity modes can be freely mixed with each other. When you use different quantities of the same kind (e.g., radius, wavelength, altitude, ...), you should probably reach for typed quantities to bring additional safety for those cases. Otherwise, just use simple mode for the remaining quantities. The mp-units library will do its best to protect your project based on the information provided.

    Tip

    You can easily mix simple and typed quantities in your project.

    "},{"location":"users_guide/framework_basics/systems_of_quantities/","title":"Systems of Quantities","text":"

    The physical units libraries on the market typically only scope on modeling one or more systems of units. However, this is not the only system kind to model. Another, and maybe even more important, system kind is a system of quantities.

    Info

    Please note that the mp-units is probably the first library on the Open Source market (in any programming language) that models the ISQ with all its definitions provided in ISO 80000. Please provide feedback if something looks odd or could be improved.

    "},{"location":"users_guide/framework_basics/systems_of_quantities/#dimension-is-not-enough-to-describe-a-quantity","title":"Dimension is not enough to describe a quantity","text":"

    Most of the products on the market are aware of physical dimensions. However, a dimension is not enough to describe a quantity. For example, let's see the following implementation:

    class Box {\n  area base_;\n  length height_;\npublic:\n  Box(length l, length w, length h) : base_(l * w), height_(h) {}\n  // ...\n};\n\nBox my_box(2 * m, 3 * m, 1 * m);\n

    How do you like such an interface? It turns out that in most existing strongly-typed libraries this is often the best we can do

    Another typical question many users ask is how to deal with work and torque. Both of those have the same dimension but are different quantities.

    A similar issue is related to figuring out what should be the result of:

    auto res = 1 * Hz + 1 * Bq + 1 * Bd;\n

    where:

    All of those quantities have the same dimension, namely \\(\\mathsf{T}^{-1}\\), but probably it is not wise to allow adding, subtracting, or comparing them, as they describe vastly different physical properties.

    If the above example seems too abstract, let's consider a fuel consumption (fuel volume divided by distance, e.g., 6.7 l/km) and an area. Again, both have the same dimension \\(\\mathsf{L}^{2}\\), but probably it wouldn't be wise to allow adding, subtracting, or comparing a fuel consumption of a car and the area of a football field. Such an operation does not have any physical sense and should fail to compile.

    Important

    More than one quantity may be defined for the same dimension:

    It turns out that the above issues can't be solved correctly without proper modeling of a system of quantities.

    "},{"location":"users_guide/framework_basics/systems_of_quantities/#quantities-of-the-same-kind","title":"Quantities of the same kind","text":"

    ISO 80000-1

    The above quotes from ISO 80000 provide answers to all the issues above. Two quantities can't be added, subtracted, or compared unless they belong to the same kind. As frequency, activity, and modulation rate are of different kinds, the expression provided above should not compile.

    "},{"location":"users_guide/framework_basics/systems_of_quantities/#system-of-quantities-is-not-only-about-kinds","title":"System of quantities is not only about kinds","text":"

    ISO 80000 specify hundreds of different quantities. There are plenty of different kinds provided and often each kind contains more than one quantity. In fact, it turns out that such quantities form a hierarchy of quantities of the same kind.

    For example, here are all quantities of the kind length provided in the ISO 80000:

    flowchart TD\n    length[\"<b>length</b><br>[m]\"]\n    length --- width[\"<b>width</b> / <b>breadth</b>\"]\n    length --- height[\"<b>height</b> / <b>depth</b> / <b>altitude</b>\"]\n    width --- thickness[\"<b>thickness</b>\"]\n    width --- diameter[\"<b>diameter</b>\"]\n    width --- radius[\"<b>radius</b>\"]\n    length --- path_length[\"<b>path_length</b>\"]\n    path_length --- distance[\"<b>distance</b>\"]\n    distance --- radial_distance[\"<b>radial_distance</b>\"]\n    length --- wavelength[\"<b>wavelength</b>\"]\n    length --- displacement[\"<b>displacement</b><br>{vector}\"]\n    displacement --- position_vector[\"<b>position_vector</b>\"]\n    radius --- radius_of_curvature[\"<b>radius_of_curvature</b>\"]

    Each of the above quantities expresses some kind of length, and each can be measured with si::metre. However, each of them has different properties, usage, and sometimes even requires a different representation type (notice that position_vector and displacement are vector quantities).

    Forming such a hierarchy helps us in defining arithmetics and conversion rules for various quantities of the same kind.

    "},{"location":"users_guide/framework_basics/systems_of_quantities/#defining-quantities","title":"Defining quantities","text":"

    In the mp-units library all the information about the quantity is provided with the quantity_spec class template. In order to define a specific quantity a user should inherit a strong type from such an instantiation.

    Tip

    Quantity specification definitions benefit from an explicit object parameter added in C++23 to remove the need for CRTP idiom, which significantly simplifies the code. However, as C++23 is far from being mainstream today, a portability macro QUANTITY_SPEC() is provided and used consistently through the library to allow the code to compile with C++20 compilers, thanks to the CRTP usage under the hood.

    See more in the C++ compiler support chapter.

    For example, here is how the above quantity kind tree can be modeled in the library:

    C++23C++20Portable 
    inline constexpr struct length final : quantity_spec<dim_length> {} length;\ninline constexpr struct width final : quantity_spec<length> {} width;\ninline constexpr auto breadth = width;\ninline constexpr struct height final : quantity_spec<length> {} height;\ninline constexpr auto depth = height;\ninline constexpr auto altitude = height;\ninline constexpr struct thickness final : quantity_spec<width> {} thickness;\ninline constexpr struct diameter final : quantity_spec<width> {} diameter;\ninline constexpr struct radius final : quantity_spec<width> {} radius;\ninline constexpr struct radius_of_curvature final : quantity_spec<radius> {} radius_of_curvature;\ninline constexpr struct path_length final : quantity_spec<length> {} path_length;\ninline constexpr auto arc_length = path_length;\ninline constexpr struct distance final : quantity_spec<path_length> {} distance;\ninline constexpr struct radial_distance final : quantity_spec<distance> {} radial_distance;\ninline constexpr struct wavelength final : quantity_spec<length> {} wavelength;\ninline constexpr struct displacement final : quantity_spec<length, quantity_character::vector> {} displacement;\ninline constexpr struct position_vector final : quantity_spec<displacement> {} position_vector;\n
    inline constexpr struct length final : quantity_spec<length, dim_length> {} length;\ninline constexpr struct width final : quantity_spec<width, length> {} width;\ninline constexpr auto breadth = width;\ninline constexpr struct height final : quantity_spec<height, length> {} height;\ninline constexpr auto depth = height;\ninline constexpr auto altitude = height;\ninline constexpr struct thickness final : quantity_spec<thickness, width> {} thickness;\ninline constexpr struct diameter final : quantity_spec<diameter, width> {} diameter;\ninline constexpr struct radius final : quantity_spec<radius, width> {} radius;\ninline constexpr struct radius_of_curvature final : quantity_spec<radius_of_curvature, radius> {} radius_of_curvature;\ninline constexpr struct path_length final : quantity_spec<path_length, length> {} path_length;\ninline constexpr auto arc_length = path_length;\ninline constexpr struct distance final : quantity_spec<distance, path_length> {} distance;\ninline constexpr struct radial_distance final : quantity_spec<radial_distance, distance> {} radial_distance;\ninline constexpr struct wavelength final : quantity_spec<wavelength, length> {} wavelength;\ninline constexpr struct displacement final : quantity_spec<displacement, length, quantity_character::vector> {} displacement;\ninline constexpr struct position_vector final : quantity_spec<position_vector, displacement> {} position_vector;\n
    QUANTITY_SPEC(length, dim_length);\nQUANTITY_SPEC(width, length);\ninline constexpr auto breadth = width;\nQUANTITY_SPEC(height, length);\ninline constexpr auto depth = height;\ninline constexpr auto altitude = height;\nQUANTITY_SPEC(thickness, width);\nQUANTITY_SPEC(diameter, width);\nQUANTITY_SPEC(radius, width);\nQUANTITY_SPEC(radius_of_curvature, radius);\nQUANTITY_SPEC(path_length, length);\ninline constexpr auto arc_length = path_length;\nQUANTITY_SPEC(distance, path_length);\nQUANTITY_SPEC(radial_distance, distance);\nQUANTITY_SPEC(wavelength, length);\nQUANTITY_SPEC(displacement, length, quantity_character::vector);\nQUANTITY_SPEC(position_vector, displacement);\n

    Note

    More information on how to define a system of quantities can be found in the \"International System of Quantities (ISQ)\" chapter.

    "},{"location":"users_guide/framework_basics/systems_of_quantities/#comparing-adding-and-subtracting-quantities","title":"Comparing, adding, and subtracting quantities","text":"

    ISO 80000 explicitly states that width and height are quantities of the same kind, and as such they:

    If we take the above for granted, the only reasonable result of 1 * width + 1 * height is 2 * length, where the result of length is known as a common quantity type. A result of such an equation is always the first common node in a hierarchy tree of the same kind. For example:

    static_assert(get_common_quantity_spec(isq::width, isq::height) == isq::length);\nstatic_assert(get_common_quantity_spec(isq::thickness, isq::radius) == isq::width);\nstatic_assert(get_common_quantity_spec(isq::distance, isq::path_length) == isq::path_length);\n
    "},{"location":"users_guide/framework_basics/systems_of_quantities/#converting-between-quantities","title":"Converting between quantities","text":"

    Based on the same hierarchy of quantities of kind length, we can define quantity conversion rules.

    1. Implicit conversions

      • every width is a length
      • every radius is a width
      static_assert(implicitly_convertible(isq::width, isq::length));\nstatic_assert(implicitly_convertible(isq::radius, isq::width));\nstatic_assert(implicitly_convertible(isq::radius, isq::length));\n

    2. Explicit conversions

      • not every length is a width
      • not every width is a radius
      static_assert(!implicitly_convertible(isq::length, isq::width));\nstatic_assert(!implicitly_convertible(isq::width, isq::radius));\nstatic_assert(!implicitly_convertible(isq::length, isq::radius));\nstatic_assert(explicitly_convertible(isq::length, isq::width));\nstatic_assert(explicitly_convertible(isq::width, isq::radius));\nstatic_assert(explicitly_convertible(isq::length, isq::radius));\n

    3. Explicit casts

      • height is not a width
      • both height and width are quantities of kind length
      static_assert(!implicitly_convertible(isq::height, isq::width));\nstatic_assert(!explicitly_convertible(isq::height, isq::width));\nstatic_assert(castable(isq::height, isq::width));\n

    4. No conversion

      • time has nothing in common with length
      static_assert(!implicitly_convertible(isq::time, isq::length));\nstatic_assert(!explicitly_convertible(isq::time, isq::length));\nstatic_assert(!castable(isq::time, isq::length));\n
    "},{"location":"users_guide/framework_basics/systems_of_quantities/#hierarchies-of-derived-quantities","title":"Hierarchies of derived quantities","text":"

    Derived quantity equations often do not automatically form a hierarchy tree. This is why it is sometimes not obvious what such a tree should look like. Also, ISO explicitly states:

    ISO/IEC Guide 99

    The division of \u2018quantity\u2019 according to \u2018kind of quantity\u2019 is, to some extent, arbitrary.

    The below presents some arbitrary hierarchy of derived quantities of kind energy:

    flowchart TD\n    energy[\"<b>energy</b><br><i>(mass * length<sup>2</sup> / time<sup>2</sup>)</i><br>[J]\"]\n    energy --- mechanical_energy[\"<b>mechanical_energy</b>\"]\n    mechanical_energy --- potential_energy[\"<b>potential_energy</b>\"]\n    potential_energy --- gravitational_potential_energy[\"<b>gravitational_potential_energy</b><br><i>(mass * acceleration_of_free_fall * height)</i>\"]\n    potential_energy --- elastic_potential_energy[\"<b>elastic_potential_energy</b><br><i>(spring_constant * amount_of_compression<sup>2</sup>)</i>\"]\n    mechanical_energy --- kinetic_energy[\"<b>kinetic_energy</b><br><i>(mass * speed<sup>2</sup>)</i>\"]\n    energy --- enthalpy[\"<b>enthalpy</b>\"]\n    enthalpy --- internal_energy[\"<b>internal_energy</b> / <b>thermodynamic_energy</b>\"]\n    internal_energy --- Helmholtz_energy[\"<b>Helmholtz_energy</b> / <b>Helmholtz_function</b>\"]\n    enthalpy --- Gibbs_energy[\"<b>Gibbs_energy</b> / <b>Gibbs_function</b>\"]\n    energy --- active_energy[\"<b>active_energy</b>\"]

    Notice, that even though all of those quantities have the same dimension and can be expressed in the same units, they have different quantity equations that can be used to create them implicitly:

    "},{"location":"users_guide/framework_basics/systems_of_quantities/#modeling-a-quantity-kind","title":"Modeling a quantity kind","text":"

    In the physical units library, we also need an abstraction describing an entire family of quantities of the same kind. Such quantities have not only the same dimension but also can be expressed in the same units.

    To annotate a quantity to represent its kind (and not just a hierarchy tree's root quantity) we introduced a kind_of<> specifier. For example, to express any quantity of length, we need to type kind_of<isq::length>.

    Important

    isq::length and kind_of<isq::length> are two different things.

    Such an entity behaves as any quantity of its kind. This means that it is implicitly convertible to any quantity in a tree.

    static_assert(!implicitly_convertible(isq::length, isq::height));\nstatic_assert(implicitly_convertible(kind_of<isq::length>, isq::height));\n

    Additionally, the result of operations on quantity kinds is also a quantity kind:

    static_assert(same_type<kind_of<isq::length> / kind_of<isq::time>, kind_of<isq::length / isq::time>>);\n

    However, if at least one equation's operand is not a quantity kind, the result becomes a \"strong\" quantity where all the kinds are converted to the hierarchy tree's root quantities:

    static_assert(!same_type<kind_of<isq::length> / isq::time, kind_of<isq::length / isq::time>>);\nstatic_assert(same_type<kind_of<isq::length> / isq::time, isq::length / isq::time>);\n

    Info

    Only a root quantity from the hierarchy tree or the one marked with is_kind specifier in the quantity_spec definition can be put as a template parameter to the kind_of specifier. For example, kind_of<isq::width> will fail to compile. However, we can call get_kind(q) to obtain a kind of any quantity:

    static_assert(get_kind(isq::width) == kind_of<isq::length>);\n
    "},{"location":"users_guide/framework_basics/systems_of_units/","title":"Systems of Units","text":"

    Modeling a system of units is probably the most important feature and a selling point of every physical units library. Thanks to that, the library can protect users from performing invalid operations on quantities and provide automated conversion factors between various compatible units.

    Probably all the libraries in the wild model the SI and many of them provide support for additional units belonging to various other systems (e.g., imperial, cgs, etc).

    "},{"location":"users_guide/framework_basics/systems_of_units/#systems-of-units-are-based-on-systems-of-quantities","title":"Systems of Units are based on Systems of Quantities","text":"

    Systems of quantities specify a set of quantities and equations relating to those quantities. Those equations do not take any unit or a numerical representation into account at all. To create a quantity, we need to add those missing pieces of information. This is where a system of units kicks in.

    The SI is explicitly stated to be based on the ISQ. Among others, it defines 7 base units, one for each base quantity. In the mp-units this is expressed by associating a quantity kind (that we discussed in detail in the previous chapter) with a unit that is used to express it:

    inline constexpr struct metre final : named_unit<\"m\", kind_of<isq::length>> {} metre;\n

    Important

    The kind_of<isq::length> above states explicitly that this unit has an associated quantity kind. In other words, si::metre (and scaled units based on it) can be used to express the amount of any quantity of kind length.

    "},{"location":"users_guide/framework_basics/systems_of_units/#units-compose","title":"Units compose","text":"

    One of the most vital points of the SI system is that its units compose. This allows providing thousands of different units for hundreds of various quantities with a tiny set of predefined units and prefixes.

    The same is modeled in the mp-units library, which also allows composing predefined units to create a nearly infinite number of different derived units. For example, one can write:

    quantity<si::metre / si::second> q;\n

    to express a quantity of speed. The resulting quantity type is implicitly inferred from the unit equation by repeating the same operations on the associated quantity kinds.

    "},{"location":"users_guide/framework_basics/systems_of_units/#many-shades-of-the-same-unit","title":"Many shades of the same unit","text":"

    The SI provides the names for 22 common coherent units of 22 derived quantities.

    Each such named derived unit is a result of a specific predefined unit equation. For example, a unit of power quantity is defined in the library as:

    inline constexpr struct watt final : named_unit<\"W\", joule / second> {} watt;\n

    However, a power quantity can be expressed in other units as well. For example, the following:

    auto q1 = 42 * W;\nstd::cout << q1 << \"\\n\";\nstd::cout << q1.in(J / s) << \"\\n\";\nstd::cout << q1.in(N * m / s) << \"\\n\";\nstd::cout << q1.in(kg * m2 / s3) << \"\\n\";\n

    prints:

    42 W\n42 J/s\n42 N m/s\n42 kg m\u00b2/s\u00b3\n

    All of the above quantities are equivalent and mean exactly the same.

    Note

    The above code example may give the impression that the order of components in a derived unit is determined by the multiplication order. This is not the case. As stated in Simplifying the resulting symbolic expressions, to be able to reason about and simplify units, the library needs to order them in an appropriate order. This will affect the order of components in a resulting type and text output.

    Please refer to our FAQ for more information.

    "},{"location":"users_guide/framework_basics/systems_of_units/#constraining-a-derived-unit-to-work-only-with-a-specific-derived-quantity","title":"Constraining a derived unit to work only with a specific derived quantity","text":"

    Some derived units are valid only for specific derived quantities. For example, SI specifies both hertz and becquerel derived units with the same unit equation 1 / s. However, it also explicitly states:

    SI Brochure

    The hertz shall only be used for periodic phenomena and the becquerel shall only be used for stochastic processes in activity referred to a radionuclide.

    The above means that the usage of becquerel as a unit of a frequency quantity is an error.

    The library allows constraining such units to work only with quantities of a specific kind in the following way:

    inline constexpr struct hertz final : named_unit<\"Hz\", one / second, kind_of<isq::frequency>> {} hertz;\ninline constexpr struct becquerel final : named_unit<\"Bq\", one / second, kind_of<isq::activity>> {} becquerel;\n

    With the above, hertz can only be used with frequencies, while becquerel should only be used with quantities of activity. This means that the following equation will not compile:

    auto q = 1 * Hz + 1 * Bq;   // Fails to compile\n

    This is exactly what we wanted to achieve to improve the type-safety of the library.

    "},{"location":"users_guide/framework_basics/systems_of_units/#prefixed-units","title":"Prefixed units","text":"

    Besides named units, the SI specifies also 24 prefixes (all being a power of 10) that can be prepended to all named units to obtain various scaled versions of them.

    Implementation of std::ratio provided by all major compilers is able to express only 16 of them. This is why, in the mp-units, we had to find an alternative way to represent unit magnitude in a more flexible way.

    Each prefix is implemented similarly to the following:

    template<PrefixableUnit U> struct quecto_ : prefixed_unit<\"q\", mag_power<10, -30>, U{}> {};\ntemplate<PrefixableUnit auto U> constexpr quecto_<decltype(U)> quecto;\n

    and then a PrefixableUnit can be prefixed in the following way:

    inline constexpr auto qm = quecto<metre>;\n

    The usage of mag_power not only enables providing support for SI prefixes, but it can also efficiently represent any rational magnitude. For example, IEC 80000 prefixes used in the IT industry can be implemented as:

    template<PrefixableUnit U> struct yobi_ : prefixed_unit<\"Yi\", mag_power<2, 80>, U{}> {};\ntemplate<PrefixableUnit auto U> constexpr yobi_<decltype(U)> yobi;\n
    "},{"location":"users_guide/framework_basics/systems_of_units/#scaled-units","title":"Scaled units","text":"

    In the SI, all units are either base or derived units or prefixed versions of those. However, those are only some of the options possible.

    For example, there is a list of off-system units accepted for use with SI. Those are scaled versions of the SI units with ratios that can't be explicitly expressed with predefined SI prefixes. Those include units like minute, hour, or electronvolt:

    inline constexpr struct minute final : named_unit<\"min\", mag<60> * si::second> {} minute;\ninline constexpr struct hour final : named_unit<\"h\", mag<60> * minute> {} hour;\ninline constexpr struct electronvolt final : named_unit<\"eV\", mag_ratio<1'602'176'634, 1'000'000'000> * mag_power<10, -19> * si::joule> {} electronvolt;\n

    Also, units of other systems of units are often defined in terms of scaled versions of the SI units. For example, the international yard is defined as:

    inline constexpr struct yard final : named_unit<\"yd\", mag_ratio<9'144, 10'000> * si::metre> {} yard;\n

    For some units, a magnitude might also be irrational. The best example here is a degree which is defined using a floating-point magnitude having a factor of the number \u03c0 (Pi):

    inline constexpr struct pi final : mag_constant<symbol_text{u8\"\u03c0\", \"pi\"}, std::numbers::pi_v<long double>> {} pi;\ninline constexpr auto \u03c0 = pi;\n
    inline constexpr struct degree final : named_unit<{u8\"\u00b0\", \"deg\"}, mag<\u03c0> / mag<180> * si::radian> {} degree;\n
    "},{"location":"users_guide/framework_basics/systems_of_units/#unit-symbols","title":"Unit symbols","text":"

    Units are available via their full names or through their short symbols. To use a long version, it is enough to type:

    quantity q1 = 42 * si::metre / si::second;\nquantity q2 = 42 * si::kilo<si::metre> / si::hour;\n

    To simplify how we spell it a short, user-friendly symbols are provided in a dedicated subnamespace in systems definitions:

    namespace si::unit_symbols {\n\nconstexpr auto m = si::metre;\nconstexpr auto km = si::kilo<si::metre>;\nconstexpr auto s = si::second;\nconstexpr auto h = si::hour;\n\n}\n

    Unit symbols introduce a lot of short identifiers into the current namespace. This is why they are opt-in. A user has to explicitly \"import\" them from a dedicated unit_symbols namespace:

    using-declarationusing-directive 
    using namespace si::unit_symbols;\n\nquantity q1 = 42 * m / s;\nquantity q2 = 42 * km / h;\n
    using si::unit_symbols::m;\nusing si::unit_symbols::km;\nusing si::unit_symbols::s;\nusing si::unit_symbols::h;\n\nquantity q1 = 42 * m / s;\nquantity q2 = 42 * km / h;\n

    We also provide alternative object identifiers using UTF-8 characters in their names for most unit symbols. The code using UTF-8 looks nicer, but it is harder to type on the keyboard. This is why we provide both versions of identifiers for such units.

    PortableWith UTF-8 glyphs 
    quantity resistance = 60 * kohm;\nquantity capacitance = 100 * uF;\n
    quantity resistance = 60 * k\u03a9;\nquantity capacitance = 100 * \u00b5F;\n
    "},{"location":"users_guide/framework_basics/systems_of_units/#common-units","title":"Common units","text":"

    Adding, subtracting, or comparing two quantities of different units will force the library to find a common unit for those. This is to prevent data truncation. For the cases when one of the units is an integral multiple of the another, the resulting quantity will use a \"smaller\" one in its result. For example:

    static_assert((1 * kg + 1 * g).unit == g);\nstatic_assert((1 * km + 1 * mm).unit == mm);\nstatic_assert((1 * yd + 1 * mi).unit == yd);\n

    However, in many cases an arithmetic operation on quantities of different units will result in a yet another unit. This happens when none of the source units is an integral multiple of another. In such cases, the library returns a special type that denotes that we are dealing with a common unit of such an equation:

    quantity q1 = 1 * km + 1 * mi;     // quantity<common_unit<international::mile, si::kilo_<si::metre>>{}, int>\nquantity q2 = 1. * rad + 1. * deg; // quantity<common_unit<si::degree, si::radian>{}, double>\n

    Note

    A user should never explicitly instantiate a common_unit class template. The library's framework will do it based on the provided quantity equation.

    "},{"location":"users_guide/framework_basics/text_output/","title":"Text Output","text":"

    Besides providing dimensional analysis and unit conversions, the library also tries hard to print any quantity in the most user-friendly way. We can print the entire quantity or its selected parts (numerical value, unit, or dimension).

    Note

    The library does not provide a text output for quantity points. The quantity stored inside is just an implementation detail of this type. It is a vector from a specific origin. Without the knowledge of the origin, the vector by itself is useless as we can't determine which point it describes.

    In the current library design, point origin does not provide any text in its definition. Even if we could add such information to the point's definition, we would not know how to output it in the text. There may be many ways to do it. For example, should we prepend or append the origin part to the quantity text?

    For example, the text output of 42 m for a quantity point may mean many things. It may be an offset from the mountain top, sea level, or maybe the center of Mars. Printing 42 m AMSL for altitudes above mean sea level is a much better solution, but the library does not have enough information to print it that way by itself.

    Please let us know if you have a good idea of how to solve this issue.

    "},{"location":"users_guide/framework_basics/text_output/#predefined-symbols","title":"Predefined symbols","text":"

    The definitions of dimensions, units, prefixes, and constants require assigning text symbols for each entity. Those symbols will be composed by the library's framework to express dimensions and units of derived quantities.

    DimensionsUnitsPrefixesConstants 
    inline constexpr struct dim_length final : base_dimension<\"L\"> {} dim_length;\ninline constexpr struct dim_mass final : base_dimension<\"M\"> {} dim_mass;\ninline constexpr struct dim_time final : base_dimension<\"T\"> {} dim_time;\ninline constexpr struct dim_electric_current final : base_dimension<\"I\"> {} dim_electric_current;\ninline constexpr struct dim_thermodynamic_temperature final : base_dimension<{u8\"\u0398\", \"O\"}> {} dim_thermodynamic_temperature;\ninline constexpr struct dim_amount_of_substance final : base_dimension<\"N\"> {} dim_amount_of_substance;\ninline constexpr struct dim_luminous_intensity final : base_dimension<\"J\"> {} dim_luminous_intensity;\n
    inline constexpr struct second final : named_unit<\"s\", kind_of<isq::time>> {} second;\ninline constexpr struct metre final : named_unit<\"m\", kind_of<isq::length>> {} metre;\ninline constexpr struct gram final : named_unit<\"g\", kind_of<isq::mass>> {} gram;\ninline constexpr auto kilogram = kilo<gram>;\n\ninline constexpr struct newton final : named_unit<\"N\", kilogram * metre / square(second)> {} newton;\ninline constexpr struct joule final : named_unit<\"J\", newton * metre> {} joule;\ninline constexpr struct watt final : named_unit<\"W\", joule / second> {} watt;\ninline constexpr struct coulomb final : named_unit<\"C\", ampere * second> {} coulomb;\ninline constexpr struct volt final : named_unit<\"V\", watt / ampere> {} volt;\ninline constexpr struct farad final : named_unit<\"F\", coulomb / volt> {} farad;\ninline constexpr struct ohm final : named_unit<{u8\"\u03a9\", \"ohm\"}, volt / ampere> {} ohm;\n
    template<PrefixableUnit U> struct micro_ : prefixed_unit<{u8\"\u00b5\", \"u\"}, mag_power<10, -6>, U{}> {};\ntemplate<PrefixableUnit U> struct milli_ : prefixed_unit<\"m\", mag_power<10, -3>, U{}> {};\ntemplate<PrefixableUnit U> struct centi_ : prefixed_unit<\"c\", mag_power<10, -2>, U{}> {};\ntemplate<PrefixableUnit U> struct deci_  : prefixed_unit<\"d\", mag_power<10, -1>, U{}> {};\ntemplate<PrefixableUnit U> struct deca_  : prefixed_unit<\"da\", mag_power<10, 1>, U{}> {};\ntemplate<PrefixableUnit U> struct hecto_ : prefixed_unit<\"h\", mag_power<10, 2>, U{}> {};\ntemplate<PrefixableUnit U> struct kilo_  : prefixed_unit<\"k\", mag_power<10, 3>, U{}> {};\ntemplate<PrefixableUnit U> struct mega_  : prefixed_unit<\"M\", mag_power<10, 6>, U{}> {};\n
    inline constexpr struct hyperfine_structure_transition_frequency_of_cs final : named_unit<{u8\"\u0394\u03bd_Cs\", \"dv_Cs\"}, mag<9'192'631'770> * hertz> {} hyperfine_structure_transition_frequency_of_cs;\ninline constexpr struct speed_of_light_in_vacuum final : named_unit<\"c\", mag<299'792'458> * metre / second> {} speed_of_light_in_vacuum;\ninline constexpr struct planck_constant final : named_unit<\"h\", mag_ratio<662'607'015, 100'000'000> * mag_power<10, -34> * joule * second> {} planck_constant;\ninline constexpr struct elementary_charge final : named_unit<\"e\", mag_ratio<1'602'176'634, 1'000'000'000> * mag_power<10, -19> * coulomb> {} elementary_charge;\ninline constexpr struct boltzmann_constant final : named_unit<\"k\", mag_ratio<1'380'649, 1'000'000> * mag_power<10, -23> * joule / kelvin> {} boltzmann_constant;\ninline constexpr struct avogadro_constant final : named_unit<\"N_A\", mag_ratio<602'214'076, 100'000'000> * mag_power<10, 23> / mole> {} avogadro_constant;\ninline constexpr struct luminous_efficacy final : named_unit<\"K_cd\", mag<683> * lumen / watt> {} luminous_efficacy;\n

    Important

    Two symbols always have to be provided if the primary symbol contains characters outside of the basic literal character set. The first must be provided as a UTF-8 literal and may contain any Unicode characters. The second one must provide an alternative spelling and only use characters from within of basic literal character set.

    Note

    Unicode provides only a minimal set of characters available as subscripts, which are often used to differentiate various constants and quantities of the same kind. To workaround this issue, mp-units uses the '_' character to specify that the following characters should be considered a subscript of the symbol.

    Tip

    For older compilers, it might be required to specify a symbol_text class explicitly template name to initialize it with two symbols:

    inline constexpr struct ohm final : named_unit<symbol_text{u8\"\u03a9\", \"ohm\"}, volt / ampere> {} ohm;\n
    "},{"location":"users_guide/framework_basics/text_output/#symbols-for-derived-entities","title":"Symbols for derived entities","text":""},{"location":"users_guide/framework_basics/text_output/#text_encoding","title":"text_encoding","text":"

    ISQ and SI standards always specify symbols using UTF-8 encoding. This is why it is a default and primary target for text output. However, in some applications or environments, a standard portable text output using only the characters from the basic literal character set can be preferred by users.

    This is why the library provides an option to change the default encoding to the portable one with:

    enum class text_encoding : std::int8_t {\n  utf8,       // \u00b5s; m\u00b3;  L\u00b2MT\u207b\u00b3\n  portable,   // us; m^3; L^2MT^-3\n  default_encoding = utf8\n};\n
    "},{"location":"users_guide/framework_basics/text_output/#symbols-of-derived-dimensions","title":"Symbols of derived dimensions","text":""},{"location":"users_guide/framework_basics/text_output/#dimension_symbol_formatting","title":"dimension_symbol_formatting","text":"

    dimension_symbol_formatting is a data type describing the configuration of the symbol generation algorithm.

    struct dimension_symbol_formatting {\n  text_encoding encoding = text_encoding::default_encoding;\n};\n
    "},{"location":"users_guide/framework_basics/text_output/#dimension_symbol","title":"dimension_symbol()","text":"

    Returns a std::string_view with the symbol of a dimension for the provided configuration:

    template<dimension_symbol_formatting fmt = dimension_symbol_formatting{}, typename CharT = char, Dimension D>\n[[nodiscard]] consteval std::string_view dimension_symbol(D);\n

    For example:

    static_assert(dimension_symbol<{.encoding = text_encoding::portable}>(isq::power.dimension) == \"L^2MT^-3\");\n

    Note

    std::string_view is returned only when C++23 is available. Otherwise, an instance of a basic_fixed_string is being returned.

    "},{"location":"users_guide/framework_basics/text_output/#dimension_symbol_to","title":"dimension_symbol_to()","text":"

    Inserts the generated dimension symbol into the output text iterator at runtime.

    template<typename CharT = char, std::output_iterator<CharT> Out, Dimension D>\nconstexpr Out dimension_symbol_to(Out out, D d, dimension_symbol_formatting fmt = dimension_symbol_formatting{});\n

    For example:

    std::string txt;\ndimension_symbol_to(std::back_inserter(txt), isq::power.dimension, {.encoding = text_encoding::portable});\nstd::cout << txt << \"\\n\";\n

    The above prints:

    L^2MT^-3\n
    "},{"location":"users_guide/framework_basics/text_output/#symbols-of-derived-units","title":"Symbols of derived units","text":""},{"location":"users_guide/framework_basics/text_output/#unit_symbol_formatting","title":"unit_symbol_formatting","text":"

    unit_symbol_formatting is a data type describing the configuration of the symbol generation algorithm. It contains three orthogonal fields, each with a default value.

    enum class unit_symbol_solidus : std::int8_t {\n  one_denominator,  // m/s;   kg m\u207b\u00b9 s\u207b\u00b9\n  always,           // m/s;   kg/(m s)\n  never,            // m s\u207b\u00b9; kg m\u207b\u00b9 s\u207b\u00b9\n  default_denominator = one_denominator\n};\n\nenum class unit_symbol_separator : std::int8_t {\n  space,          // kg m\u00b2/s\u00b2\n  half_high_dot,  // kg\u22c5m\u00b2/s\u00b2  (valid only for utf8 encoding)\n  default_separator = space\n};\n\nstruct unit_symbol_formatting {\n  text_encoding encoding = text_encoding::default_encoding;\n  unit_symbol_solidus solidus = unit_symbol_solidus::default_denominator;\n  unit_symbol_separator separator = unit_symbol_separator::default_separator;\n};\n

    unit_symbol_solidus impacts how the division of unit symbols is being presented in the text output. By default, the '/' will be printed if only one unit component is in the denominator. Otherwise, the exponent syntax will be used.

    unit_symbol_separator specifies how multiple multiplied units should be separated from each other. By default, the space (' ') will be used as a separator.

    "},{"location":"users_guide/framework_basics/text_output/#unit_symbol","title":"unit_symbol()","text":"

    Returns a std::string_view with the symbol of a unit for the provided configuration:

    template<unit_symbol_formatting fmt = unit_symbol_formatting{}, typename CharT = char, Unit U>\n[[nodiscard]] consteval std::string_view unit_symbol(U);\n

    For example:

    static_assert(unit_symbol<{.solidus = unit_symbol_solidus::never,\n                           .separator = unit_symbol_separator::half_high_dot}>(kg * m / s2) == \"kg\u22c5m\u22c5s\u207b\u00b2\");\n
    "},{"location":"users_guide/framework_basics/text_output/#unit_symbol_to","title":"unit_symbol_to()","text":"

    Inserts the generated unit symbol into the output text iterator at runtime.

    template<typename CharT = char, std::output_iterator<CharT> Out, Unit U>\nconstexpr Out unit_symbol_to(Out out, U u, unit_symbol_formatting fmt = unit_symbol_formatting{});\n

    For example:

    std::string txt;\nunit_symbol_to(std::back_inserter(txt), kg * m / s2,\n               {.solidus = unit_symbol_solidus::never, .separator = unit_symbol_separator::half_high_dot});\nstd::cout << txt << \"\\n\";\n

    The above prints:

    kg\u22c5m\u22c5s\u207b\u00b2\n
    "},{"location":"users_guide/framework_basics/text_output/#symbols-of-scaled-units","title":"Symbols of scaled units","text":"

    In most cases scaled units are hidden behind named units. However, there are a few real-life where a user directly faces a scaled unit. For example:

    constexpr Unit auto L_per_100km = L / (mag<100> * km);\n

    The above is a derived unit of litre divided by a scaled unit of 100 kilometers. As we can see a scaled unit has a magnitude and a reference unit. To denote the scope of such a unit, we enclose it in [...]. For example, the following:

    std::cout << 6.7 * L_per_100km << \"\\n\";\n

    prints:

    6.7 L/[100 km]\n
    "},{"location":"users_guide/framework_basics/text_output/#symbols-of-common-units","title":"Symbols of common units","text":"

    Some common units expressed with a specialization of the common_unit class template need special printing rules for their symbols. As they represent a minimum set of equivalent common units resulting from the addition or subtraction of multiple quantities, we print all of them as a scaled version of the source unit. For example, the following:

    std::cout << 1 * km + 1 * mi << \"\\n\";\nstd::cout << 1 * nmi + 1 * mi << \"\\n\";\nstd::cout << 1 * km / h + 1 * m / s << \"\\n\";\nstd::cout << 1 * rad + 1 * deg << \"\\n\";\n

    prints:

    40771 [(1/25146 mi), (1/15625 km)]\n108167 [(1/50292 mi), (1/57875 nmi)]\n23 [(1/5 km/h), (1/18 m/s)]\n183.142 [(1/\u03c0\u00b0), (1/180 rad)]\n

    Thanks to the above, it might be easier for the user to reason about the magnitude of the resulting unit and its impact on the value stored in the quantity.

    Note

    It is important to note that this output is provided only for intermediate results of the equations, as shown above. A user usually knows which unit should be used, and explicit conversion can be made to achieve that. For example:

    std::cout << (1 * km + 1 * mi).in<double>(km) << \"\\n\";\n

    prints:

    2.60934 km\n
    "},{"location":"users_guide/framework_basics/text_output/#space_before_unit_symbol-customization-point","title":"space_before_unit_symbol customization point","text":"

    The SI Brochure says:

    SI Brochure

    The numerical value always precedes the unit and a space is always used to separate the unit from the number. ... The only exceptions to this rule are for the unit symbols for degree, minute and second for plane angle, \u00b0, \u2032 and \u2033, respectively, for which no space is left between the numerical value and the unit symbol.

    There are more units with such properties. For example, percent (%) and per mille(\u2030).

    To support the above and other similar cases, the library exposes space_before_unit_symbol customization point. By default, its value is true for all the units, so the space between a number and a unit will be inserted in the output text. To change this behavior, we have to provide a partial specialization for a specific unit:

    template<>\nconstexpr bool space_before_unit_symbol<non_si::degree> = false;\n

    Note

    The above works only for the default formatting or for the format strings that use %? placement field (std::format(\"{}\", q) is equivalent to std::format(\"{:%N%?%U}\", q)).

    In case a user provides custom format specification (e.g., std::format(\"{:%N %U}\", q)), the library will always obey this specification for all the units (no matter what the actual value of the space_before_unit_symbol customization point is) and the separating space will always be used in this case.

    "},{"location":"users_guide/framework_basics/text_output/#output-streams","title":"Output streams","text":"

    Tip

    The output streaming support is opt-in and can be enabled by including the <mp-units/ostream.h> header file.

    The easiest way to print a dimension, unit, or quantity is to provide its object to the output stream:

    const QuantityOf<isq::speed> auto v1 = avg_speed(220. * km, 2 * h);\nconst QuantityOf<isq::speed> auto v2 = avg_speed(140. * mi, 2 * h);\nstd::cout << v1 << '\\n';            // 110 km/h\nstd::cout << v2 << '\\n';            // 70 mi/h\nstd::cout << v2.unit << '\\n';       // mi/h\nstd::cout << v2.dimension << '\\n';  // LT\u207b\u00b9\n

    The text output will always print the value using the default formatting for this entity.

    Important: Don't assume a unit

    Remember that when we deal with a quantity of an \"unknown\" (e.g., auto) type, it is a good practice to always convert the unit to the expected one before passing it to the text output:

    std::cout << v1.in(km / h) << '\\n';       // 110 km/h\nstd::cout << v1.force_in(m / s) << '\\n';  // 30.5556 m/s\n
    "},{"location":"users_guide/framework_basics/text_output/#output-stream-formatting","title":"Output stream formatting","text":"

    Only basic formatting can be applied to output streams. It includes control over width, fill, and alignment.

    The numerical value of the quantity will be printed according to the current stream state and standard manipulators may be used to customize that (assuming that the underlying representation type respects them).

    std::cout << \"|\" << std::setw(10) << 123 * m << \"|\\n\";                       // |     123 m|\nstd::cout << \"|\" << std::setw(10) << std::left << 123 * m << \"|\\n\";          // |123 m     |\nstd::cout << \"|\" << std::setw(10) << std::setfill('*') << 123 * m << \"|\\n\";  // |123 m*****|\n

    Note

    To have more control over the formatting of the quantity that is printed with the output stream just use std::cout << std::format(...).

    "},{"location":"users_guide/framework_basics/text_output/#text-formatting","title":"Text formatting","text":"

    The library provides custom formatters for std::format facility, which allows fine-grained control over what and how it is being printed in the text output.

    Tip

    The text formatting facility support is opt-in and can be enabled by including the <mp-units/format.h> header file.

    "},{"location":"users_guide/framework_basics/text_output/#controlling-width-fill-and-alignment","title":"Controlling width, fill, and alignment","text":"

    Formatting grammar for all the entities provides control over width, fill, and alignment. The C++ standard grammar tokens fill-and-align and width are being used. They treat the entity as a contiguous text to be aligned. For example, here are a few examples of the quantity numerical value and symbol formatting:

    std::println(\"|{:0}|\", 123 * m);     // |123 m|\nstd::println(\"|{:10}|\", 123 * m);    // |     123 m|\nstd::println(\"|{:<10}|\", 123 * m);   // |123 m     |\nstd::println(\"|{:>10}|\", 123 * m);   // |     123 m|\nstd::println(\"|{:^10}|\", 123 * m);   // |  123 m   |\nstd::println(\"|{:*<10}|\", 123 * m);  // |123 m*****|\nstd::println(\"|{:*>10}|\", 123 * m);  // |*****123 m|\nstd::println(\"|{:*^10}|\", 123 * m);  // |**123 m***|\n

    It is important to note that in the second line above, the quantity text is aligned to the right by default, which is consistent with the formatting of numeric types. Units and dimensions behave as text and, thus, are aligned to the left by default.

    Note

    std::println is a C++23 facility. In case we do not have access to C++23, we can obtain the same output with:

    std::cout << std::format(\"<format-string>\\n\", <format-args>);\n
    "},{"location":"users_guide/framework_basics/text_output/#dimension-formatting","title":"Dimension formatting","text":"
    dimension-format-spec = [fill-and-align], [width], [dimension-spec];\ndimension-spec        = [character-set];\ncharacter-set         = 'U' | 'P';\n

    In the above grammar:

    Dimension symbols of some quantities are specified to use Unicode signs by the ISQ (e.g., \u0398 symbol for the thermodynamic temperature dimension). The library follows this by default. From the engineering point of view, sometimes Unicode text might not be the best solution, as terminals of many (especially embedded) devices can output only letters from the basic literal character set. In such a case, the dimension symbol can be forced to be printed using such characters thanks to character-set token:

    std::println(\"{}\", isq::dim_thermodynamic_temperature);   // \u0398\nstd::println(\"{:P}\", isq::dim_thermodynamic_temperature); // O\nstd::println(\"{}\", isq::power.dimension);                 // L\u00b2MT\u207b\u00b3\nstd::println(\"{:P}\", isq::power.dimension);               // L^2MT^-3\n
    "},{"location":"users_guide/framework_basics/text_output/#unit-formatting","title":"Unit formatting","text":"
    unit-format-spec      = [fill-and-align], [width], [unit-spec];\nunit-spec             = [character-set], [unit-symbol-solidus], [unit-symbol-separator], [L]\n                      | [character-set], [unit-symbol-separator], [unit-symbol-solidus], [L]\n                      | [unit-symbol-solidus], [character-set], [unit-symbol-separator], [L]\n                      | [unit-symbol-solidus], [unit-symbol-separator], [character-set], [L]\n                      | [unit-symbol-separator], [character-set], [unit-symbol-solidus], [L]\n                      | [unit-symbol-separator], [unit-symbol-solidus], [character-set], [L];\nunit-symbol-solidus   = '1' | 'a' | 'n';\nunit-symbol-separator = 's' | 'd';\n

    In the above grammar:

    Note

    The above grammar intended that the elements of unit-spec can appear in any order as they have unique characters. Users shouldn't have to remember the order of those tokens to control the formatting of a unit symbol.

    Unit symbols of some quantities are specified to use Unicode signs by the SI (e.g., \u03a9 symbol for the resistance quantity). The library follows this by default. From the engineering point of view, Unicode text might not be the best solution sometimes, as terminals of many (especially embedded) devices can output only letters from the basic literal character set. In such a case, the unit symbol can be forced to be printed using such characters thanks to character-set token:

    std::println(\"{}\", si::ohm);      // \u03a9\nstd::println(\"{:P}\", si::ohm);    // ohm\nstd::println(\"{}\", us);           // \u00b5s\nstd::println(\"{:P}\", us);         // us\nstd::println(\"{}\", m / s2);       // m/s\u00b2\nstd::println(\"{:P}\", m / s2);     // m/s^2\n

    Additionally, both ISO 80000 and SI leave some freedom on how to print unit symbols. This is why two additional tokens were introduced.

    unit-symbol-solidus specifies how the division of units should look like. By default, / will be used only when the denominator contains only one unit. However, with the 'a' or 'n' options, we can force the facility to print the / character always (even when there are more units in the denominator), or never, in which case a parenthesis will be added to enclose all denominator units.

    std::println(\"{}\", m / s);          // m/s\nstd::println(\"{}\", kg / m / s2);    // kg m\u207b\u00b9 s\u207b\u00b2\nstd::println(\"{:a}\", m / s);        // m/s\nstd::println(\"{:a}\", kg / m / s2);  // kg/(m s\u00b2)\nstd::println(\"{:n}\", m / s);        // m s\u207b\u00b9\nstd::println(\"{:n}\", kg / m / s2);  // kg m\u207b\u00b9 s\u207b\u00b2\n

    The unit-symbol-separator token allows us to obtain the following outputs:

    std::println(\"{}\", kg * m2 / s2);    // kg m\u00b2/s\u00b2\nstd::println(\"{:d}\", kg * m2 / s2);  // kg\u22c5m\u00b2/s\u00b2\n

    Note

    'd' requires the UTF-8 encoding to be set.

    "},{"location":"users_guide/framework_basics/text_output/#quantity-formatting","title":"Quantity formatting","text":"
    quantity-format-spec        = [fill-and-align], [width], [quantity-specs], [defaults-specs];\nquantity-specs              = conversion-spec;\n                            | quantity-specs, conversion-spec;\n                            | quantity-specs, literal-char;\nliteral-char                = ? any character other than '{', '}', or '%' ?;\nconversion-spec             = '%', placement-type;\nplacement-type              = subentity-id | '?' | '%';\ndefaults-specs              = ':', default-spec-list;\ndefault-spec-list           = default-spec;\n                            | default-spec-list, default-spec;\ndefault-spec                = subentity-id, '[' format-spec ']';\nsubentity-id                = 'N' | 'U' | 'D';\nformat-spec                 = ? as specified by the formatter for the argument type ?;\n

    In the above grammar:

    "},{"location":"users_guide/framework_basics/text_output/#default-formatting","title":"Default formatting","text":"

    To format quantity values, the formatting facility uses quantity-format-spec. If left empty, the default formatting is applied. The same default formatting is also applied to the output streams. This is why the following code lines produce the same output:

    std::cout << \"Distance: \" << 123 * km << \"\\n\";\nstd::cout << std::format(\"Distance: {}\\n\", 123 * km);\nstd::cout << std::format(\"Distance: {:%N%?%U}\\n\", 123 * km);\n

    Note

    For some quantities, the {:%N %U} format may provide a different output than the default one, as some units have space_before_unit_symbol customization point explicitly set to false (e.g., % and \u00b0).

    "},{"location":"users_guide/framework_basics/text_output/#quantity-numerical-value-unit-symbol-or-both","title":"Quantity numerical value, unit symbol, or both?","text":"

    Thanks to the grammar provided above, the user can easily decide to either:

    "},{"location":"users_guide/framework_basics/text_output/#formatting-of-the-quantity-numerical-value","title":"Formatting of the quantity numerical value","text":"

    The representation type used as a numerical value of a quantity must provide its own formatter specialization. It will be called by the quantity formatter with the format-spec provided by the user in the N defaults specification.

    In case we use C++ fundamental arithmetic types with our quantities the standard formatter specified in format.string.std will be used. The rest of this chapter assumes that it is the case and provides some usage examples.

    sign token allows us to specify how the value's sign is being printed:

    std::println(\"{0},{0::N[+]},{0::N[-]},{0::N[ ]}\", 1 * m);   // 1 m,+1 m,1 m, 1 m\nstd::println(\"{0},{0::N[+]},{0::N[-]},{0::N[ ]}\", -1 * m);  // -1 m,-1 m,-1 m,-1 m\n

    where:

    precision token is allowed only for floating-point representation types:

    std::println(\"{::N[.0]}\", 1.2345 * m);   // 1 m\nstd::println(\"{::N[.1]}\", 1.2345 * m);   // 1 m\nstd::println(\"{::N[.2]}\", 1.2345 * m);   // 1.2 m\nstd::println(\"{::N[.3]}\", 1.2345 * m);   // 1.23 m\nstd::println(\"{::N[.0f]}\", 1.2345 * m);  // 1 m\nstd::println(\"{::N[.1f]}\", 1.2345 * m);  // 1.2 m\nstd::println(\"{::N[.2f]}\", 1.2345 * m);  // 1.23 m\n

    type specifies how a value of the representation type is being printed. For integral types:

    std::println(\"{::N[b]}\", 42 * m);    // 101010 m\nstd::println(\"{::N[B]}\", 42 * m);    // 101010 m\nstd::println(\"{::N[d]}\", 42 * m);    // 42 m\nstd::println(\"{::N[o]}\", 42 * m);    // 52 m\nstd::println(\"{::N[x]}\", 42 * m);    // 2a m\nstd::println(\"{::N[X]}\", 42 * m);    // 2A m\n

    The above can be printed in an alternate version thanks to the # token:

    std::println(\"{::N[#b]}\", 42 * m);   // 0b101010 m\nstd::println(\"{::N[#B]}\", 42 * m);   // 0B101010 m\nstd::println(\"{::N[#o]}\", 42 * m);   // 052 m\nstd::println(\"{::N[#x]}\", 42 * m);   // 0x2a m\nstd::println(\"{::N[#X]}\", 42 * m);   // 0X2A m\n

    For floating-point values, the type token works as follows:

    std::println(\"{::N[a]}\",   1.2345678 * m);      // 1.3c0ca2a5b1d5dp+0 m\nstd::println(\"{::N[.3a]}\", 1.2345678 * m);      // 1.3c1p+0 m\nstd::println(\"{::N[A]}\",   1.2345678 * m);      // 1.3C0CA2A5B1D5DP+0 m\nstd::println(\"{::N[.3A]}\", 1.2345678 * m);      // 1.3C1P+0 m\nstd::println(\"{::N[e]}\",   1.2345678 * m);      // 1.234568e+00 m\nstd::println(\"{::N[.3e]}\", 1.2345678 * m);      // 1.235e+00 m\nstd::println(\"{::N[E]}\",   1.2345678 * m);      // 1.234568E+00 m\nstd::println(\"{::N[.3E]}\", 1.2345678 * m);      // 1.235E+00 m\nstd::println(\"{::N[g]}\",   1.2345678 * m);      // 1.23457 m\nstd::println(\"{::N[g]}\",   1.2345678e8 * m);    // 1.23457e+08 m\nstd::println(\"{::N[.3g]}\", 1.2345678 * m);      // 1.23 m\nstd::println(\"{::N[.3g]}\", 1.2345678e8 * m);    // 1.23e+08 m\nstd::println(\"{::N[G]}\",   1.2345678 * m);      // 1.23457 m\nstd::println(\"{::N[G]}\",   1.2345678e8 * m);    // 1.23457E+08 m\nstd::println(\"{::N[.3G]}\", 1.2345678 * m);      // 1.23 m\nstd::println(\"{::N[.3G]}\", 1.2345678e8 * m);    // 1.23E+08 m\n
    "},{"location":"users_guide/framework_basics/the_affine_space/","title":"The Affine Space","text":"

    The affine space has two types of entities:

    In the following subchapters, we will often refer to displacement vectors simply as vectors for brevity.

    Note

    The displacement vector described here is specific to the affine space theory and is not the same thing as the quantity of a vector character that we discussed in the \"Scalars, vectors, and tensors\" chapter (although, in some cases, those terms may overlap).

    "},{"location":"users_guide/framework_basics/the_affine_space/#operations-in-the-affine-space","title":"Operations in the affine space","text":"

    Here are the primary operations one can do in the affine space:

    Important

    It is not possible to:

    "},{"location":"users_guide/framework_basics/the_affine_space/#points-are-more-common-than-most-of-us-imagine","title":"Points are more common than most of us imagine","text":"

    Point abstractions should be used more often in the C++ software. They are not only about temperature or time. Points are everywhere around us and should become more popular in the products we implement. They can be used to implement:

    Improving the affine space's Points intuition will allow us to write better and safer software.

    "},{"location":"users_guide/framework_basics/the_affine_space/#displacement-vector-is-modeled-by-quantity","title":"Displacement vector is modeled by quantity","text":"

    Up until now, each time we used a quantity in our code, we were modeling some kind of a difference between two things:

    As we already know, a quantity type provides all operations required for a displacement vector abstraction in the affine space. It can be constructed with:

    Note

    The multiply syntax support is disabled for units that provide a point origin in their definition (i.e., units of temperature like K, deg_C, and deg_F).

    "},{"location":"users_guide/framework_basics/the_affine_space/#point-is-modeled-by-quantity_point-and-pointorigin","title":"Point is modeled by quantity_point and PointOrigin","text":"

    In the mp-units library, the Point abstraction is modelled by:

    "},{"location":"users_guide/framework_basics/the_affine_space/#quantity_point","title":"quantity_point","text":"

    The quantity_point class template specifies an absolute quantity measured from a predefined origin:

    template<Reference auto R,\n         PointOriginFor<get_quantity_spec(R)> auto PO = default_point_origin(R),\n         RepresentationOf<get_quantity_spec(R)> Rep = double>\nclass quantity_point;\n

    As we can see above, the quantity_point class template exposes one additional parameter compared to quantity. The PO parameter satisfies a PointOriginFor concept and specifies the origin of our measurement scale.

    Each quantity_point internally stores a quantity object, which represents a displacement vector from the predefined origin. Thanks to this, an instantiation of a quantity_point can be considered as a model of a vector space from such an origin.

    Forcing the user to manually predefine an origin for every domain may be cumbersome and discourage users from using such abstractions at all. This is why, by default, the PO template parameter is initialized with the default_point_origin(R) that provides the quantity points' scale zeroth point using the following rules:

    Quantity points with default point origins may be constructed with the point construction helper or forcing an explicit conversion from the quantity:

    // quantity_point qp1 = 42 * m;           // Compile-time error\n// quantity_point qp2 = 42 * K;           // Compile-time error\n// quantity_point qp3 = delta<deg_C>(42); // Compile-time error\nquantity_point qp4(42 * m);\nquantity_point qp5(42 * K);\nquantity_point qp6(delta<deg_C>(42));\nquantity_point qp7 = point<m>(42);\nquantity_point qp8 = point<K>(42);\nquantity_point qp9 = point<deg_C>(42);\n

    Tip

    The quantity_point definition can be found in the mp-units/quantity_point.h header file.

    "},{"location":"users_guide/framework_basics/the_affine_space/#zeroth_point_originquantityspec","title":"zeroth_point_origin<QuantitySpec>","text":"

    zeroth_point_origin<QuantitySpec> is meant to be used in cases where the specific domain has a well-established, non-controversial, and unique zeroth point on the measurement scale. This saves the user from the need to write a boilerplate code that would predefine such a type for this domain.

    quantity_point<isq::distance[si::metre]> qp1(100 * m);\nquantity_point<isq::distance[si::metre]> qp2 = point<m>(120);\n\nassert(qp1.quantity_from_zero() == 100 * m);\nassert(qp2.quantity_from_zero() == 120 * m);\nassert(qp2.quantity_from(qp1) == 20 * m);\nassert(qp1.quantity_from(qp2) == -20 * m);\n\nassert(qp2 - qp1 == 20 * m);\nassert(qp1 - qp2 == -20 * m);\n\n// auto res = qp1 + qp2;   // Compile-time error\n

    In the above code 100 * m and 120 * m still create two quantities that serve as displacement vectors here. Quantity point objects can be explicitly constructed from such quantities only when their origin is an instantiation of the zeroth_point_origin<QuantitySpec>.

    It is really important to understand that even though we can use .quantity_from_zero() to obtain the displacement vector of a point from the origin, the point by itself does not represent or have any associated physical value. It is just a point in some space. The same point can be expressed with different displacement vectors from different origins.

    It is also worth mentioning that simplicity comes with a safety cost here. For some users, it might be surprising that the usage of zeroth_point_origin<QuantitySpec> makes various quantity point objects compatible as long as quantity types used in the origin and reference are compatible:

    quantity_point<si::metre> qp1{isq::distance(100 * m)};\nquantity_point<si::metre> qp2 = point<isq::height[m]>(120);\n\nassert(qp2.quantity_from(qp1) == 20 * m);\nassert(qp1.quantity_from(qp2) == -20 * m);\nassert(qp2 - qp1 == 20 * m);\nassert(qp1 - qp2 == -20 * m);\n
    "},{"location":"users_guide/framework_basics/the_affine_space/#absolute-point-origin","title":"Absolute point origin","text":"

    In cases where we want to implement an isolated independent space in which points are not compatible with other spaces, even of the same quantity type, we should manually predefine an absolute point origin.

    inline constexpr struct origin final : absolute_point_origin<isq::distance> {} origin;\n\n// quantity_point<si::metre, origin> qp1{100 * m};        // Compile-time error\n// quantity_point<si::metre, origin> qp2{delta<m>(120)};  // Compile-time error\nquantity_point<si::metre, origin> qp1 = origin + 100 * m;\nquantity_point<si::metre, origin> qp2 = 120 * m + origin;\n\n// assert(qp1.quantity_from_zero() == 100 * m);   // Compile-time error\n// assert(qp2.quantity_from_zero() == 120 * m);   // Compile-time error\nassert(qp1.quantity_from(origin) == 100 * m);\nassert(qp2.quantity_from(origin) == 120 * m);\nassert(qp2.quantity_from(qp1) == 20 * m);\nassert(qp1.quantity_from(qp2) == -20 * m);\n\nassert(qp1 - origin == 100 * m);\nassert(qp2 - origin == 120 * m);\nassert(qp2 - qp1 == 20 * m);\nassert(qp1 - qp2 == -20 * m);\n\nassert(origin - qp1 == -100 * m);\nassert(origin - qp2 == -120 * m);\n\n// assert(origin - origin == 0 * m);   // Compile-time error\n

    We can't construct a quantity point directly from the quantity anymore when a custom, named origin is used. To prevent potential safety and maintenance issues, we always need to explicitly provide both a compatible origin and a quantity measured from it to construct a quantity point.

    Said otherwise, a quantity point defined in terms of a specific origin is the result of adding the origin and the displacement vector measured from it to the point we create.

    Info

    A rationale for this longer construction syntax can be found in the Why can't I create a quantity by passing a number to a constructor? chapter.

    Similarly to creation of a quantity, if someone does not like the operator-based syntax to create a quantity_point, the same results can be achieved with a two-parameter constructor:

    quantity_point qp1{100 * m, origin};\n

    Again, CTAD always helps to use precisely the type we need in a current case.

    Additionally, if a quantity point is defined in terms of a custom, named origin, then we can't use a quantity_from_zero() member function anymore. This is to prevent surprises, as our origin may not necessarily be perceived as an absolute zero in the domain we model. Also, as we will learn soon, we can define several related origins in one space, and then it gets harder to understand which one is the \"zero\" one. This is why, to be specific and always correct about the points we use, a quantity_from(QP) member function can be used (where QP can either be an origin or another quantity point).

    Finally, please note that it is not allowed to subtract two point origins defined in terms of absolute_point_origin (e.g., origin - origin) as those do not contain information about the unit, so we cannot determine a resulting quantity type.

    "},{"location":"users_guide/framework_basics/the_affine_space/#modeling-independent-spaces-in-one-domain","title":"Modeling independent spaces in one domain","text":"

    Absolute point origins are also perfect for establishing independent spaces even if the same quantity type and unit is being used:

    inline constexpr struct origin1 final : absolute_point_origin<isq::distance> {} origin1;\ninline constexpr struct origin2 final : absolute_point_origin<isq::distance> {} origin2;\n\nquantity_point qp1 = origin1 + 100 * m;\nquantity_point qp2 = origin2 + 120 * m;\n\nassert(qp1.quantity_from(origin1) == 100 * m);\nassert(qp2.quantity_from(origin2) == 120 * m);\n\nassert(qp1 - origin1 == 100 * m);\nassert(qp2 - origin2 == 120 * m);\nassert(origin1 - qp1 == -100 * m);\nassert(origin2 - qp2 == -120 * m);\n\n// assert(qp2 - qp1 == 20 * m);                    // Compile-time error\n// assert(qp1 - origin2 == 100 * m);               // Compile-time error\n// assert(qp2 - origin1 == 120 * m);               // Compile-time error\n// assert(qp2.quantity_from(qp1) == 20 * m);       // Compile-time error\n// assert(qp1.quantity_from(origin2) == 100 * m);  // Compile-time error\n// assert(qp2.quantity_from(origin1) == 120 * m);  // Compile-time error\n
    "},{"location":"users_guide/framework_basics/the_affine_space/#relative-point-origin","title":"Relative Point origin","text":"

    We often do not have only one ultimate \"zero\" point when we measure things. Often, we have one common scale, but we measure various quantities relative to different points and expect those points to be compatible. There are many examples here, but probably the most common are temperatures, timestamps, and altitudes.

    For such cases, relative point origins should be used:

    inline constexpr struct A final : absolute_point_origin<isq::distance> {} A;\ninline constexpr struct B final : relative_point_origin<A + 10 * m> {} B;\ninline constexpr struct C final : relative_point_origin<B + 10 * m> {} C;\ninline constexpr struct D final : relative_point_origin<A + 30 * m> {} D;\n\nquantity_point qp1 = C + 100 * m;\nquantity_point qp2 = D + 120 * m;\n\nassert(qp1.quantity_ref_from(qp1.point_origin) == 100 * m);\nassert(qp2.quantity_ref_from(qp2.point_origin) == 120 * m);\n\nassert(qp2.quantity_from(qp1) == 30 * m);\nassert(qp1.quantity_from(qp2) == -30 * m);\nassert(qp2 - qp1 == 30 * m);\nassert(qp1 - qp2 == -30 * m);\n\nassert(qp1.quantity_from(A) == 120 * m);\nassert(qp1.quantity_from(B) == 110 * m);\nassert(qp1.quantity_from(C) == 100 * m);\nassert(qp1.quantity_from(D) == 90 * m);\nassert(qp1 - A == 120 * m);\nassert(qp1 - B == 110 * m);\nassert(qp1 - C == 100 * m);\nassert(qp1 - D == 90 * m);\n\nassert(qp2.quantity_from(A) == 150 * m);\nassert(qp2.quantity_from(B) == 140 * m);\nassert(qp2.quantity_from(C) == 130 * m);\nassert(qp2.quantity_from(D) == 120 * m);\nassert(qp2 - A == 150 * m);\nassert(qp2 - B == 140 * m);\nassert(qp2 - C == 130 * m);\nassert(qp2 - D == 120 * m);\n\nassert(B - A == 10 * m);\nassert(C - A == 20 * m);\nassert(D - A == 30 * m);\nassert(D - C == 10 * m);\n\nassert(B - B == 0 * m);\n// assert(A - A == 0 * m);  // Compile-time error\n

    Note

    Even though we can't subtract two absolute point origins from each other, it is possible to subtract relative ones or relative and absolute ones.

    "},{"location":"users_guide/framework_basics/the_affine_space/#converting-between-different-representations-of-the-same-point","title":"Converting between different representations of the same point","text":"

    As we might represent the same point with displacement vectors from various origins, the library provides facilities to convert the same point to the quantity_point class templates expressed in terms of different origins.

    For this purpose, we can use either:

    It is important to understand that all such translations still describe exactly the same point (e.g., all of them compare equal):

    assert(qp2 == qp2C);\nassert(qp2 == qp2B);\nassert(qp2 == qp2A);\n

    Important

    It is only allowed to convert between various origins defined in terms of the same absolute_point_origin. Even if it is possible to express the same point as a displacement vector from another absolute_point_origin, the library will not provide such a conversion. A custom user-defined conversion function will be needed to add such a functionality.

    Said another way, in the library, there is no way to spell how two distinct absolute_point_origin types relate to each other.

    "},{"location":"users_guide/framework_basics/the_affine_space/#temperature-support","title":"Temperature support","text":"

    Support for temperature quantity points is probably one of the most common examples of relative point origins in action that we use in daily life.

    The SI definition in the library provides a few predefined point origins for this purpose:

    namespace si {\n\ninline constexpr struct absolute_zero final : absolute_point_origin<isq::thermodynamic_temperature> {} absolute_zero;\ninline constexpr auto zeroth_kelvin = absolute_zero;\n\ninline constexpr struct ice_point final : relative_point_origin<point<milli<kelvin>>(273'150)}> {} ice_point;\ninline constexpr auto zeroth_degree_Celsius = ice_point;\n\n}\n\nnamespace usc {\n\ninline constexpr struct zeroth_degree_Fahrenheit final :\n  relative_point_origin<point<mag_ratio<5, 9> * si::degree_Celsius>(-32)> {} zeroth_degree_Fahrenheit;\n\n}\n

    The above is a great example of how point origins can be stacked on top of each other:

    Note

    Notice that while stacking point origins, we can use different representation types and units for origins and a point. In the above example, the relative point origin for degree Celsius is defined in terms of si::kelvin, while the quantity point for it will use si::degree_Celsius as a unit.

    The temperature point origins defined above are provided explicitly in the respective units' definitions:

    namespace si {\n\ninline constexpr struct kelvin final :\n    named_unit<\"K\", kind_of<isq::thermodynamic_temperature>, zeroth_kelvin> {} kelvin;\ninline constexpr struct degree_Celsius final :\n    named_unit<{u8\"\u2103\", \"`C\"}, kelvin, zeroth_degree_Celsius> {} degree_Celsius;\n\n}\n\nnamespace usc {\n\ninline constexpr struct degree_Fahrenheit final :\n    named_unit<{u8\"\u2109\", \"`F\"}, mag_ratio<5, 9> * si::degree_Celsius,\n               zeroth_degree_Fahrenheit> {} degree_Fahrenheit;\n\n}\n

    As it was described above, default_point_origin(R) returns a zeroth_point_origin<QuantitySpec> when a unit does not provide any origin in its definition. As of today, the units of temperature are the only ones in the entire mp-units library that provide such origins.

    Now, let's see how we can benefit from the above definitions. We have quite a few alternatives to choose from here. Depending on our needs or tastes, we can:

    In all of the above cases, we end up with the quantity_point of the same type and value.

    To play a bit more with temperatures, we can implement a simple room AC temperature controller in the following way:

    constexpr struct room_reference_temp final : relative_point_origin<point<deg_C>(21)> {} room_reference_temp;\nusing room_temp = quantity_point<isq::Celsius_temperature[deg_C], room_reference_temp>;\n\nconstexpr auto step_delta = delta<isq::Celsius_temperature<deg_C>>(0.5);\nconstexpr int number_of_steps = 6;\n\nroom_temp room_ref{};\nroom_temp room_low = room_ref - number_of_steps * step_delta;\nroom_temp room_high = room_ref + number_of_steps * step_delta;\n\nstd::println(\"Room reference temperature: {} ({}, {::N[.2f]})\\n\",\n             room_ref.quantity_from_zero(),\n             room_ref.in(usc::degree_Fahrenheit).quantity_from_zero(),\n             room_ref.in(si::kelvin).quantity_from_zero());\n\nstd::println(\"| {:<18} | {:^18} | {:^18} | {:^18} |\",\n             \"Temperature delta\", \"Room reference\", \"Ice point\", \"Absolute zero\");\nstd::println(\"|{0:=^20}|{0:=^20}|{0:=^20}|{0:=^20}|\", \"\");\n\nauto print_temp = [&](std::string_view label, auto v) {\n  std::println(\"| {:<14} | {:^18} | {:^18} | {:^18:N[.2f]} |\", label,\n               v - room_reference_temp, (v - si::ice_point).in(deg_C), (v - si::absolute_zero).in(deg_C));\n};\n\nprint_temp(\"Lowest\", room_low);\nprint_temp(\"Default\", room_ref);\nprint_temp(\"Highest\", room_high);\n

    The above prints:

    Room reference temperature: 21 \u2103 (69.8 \u2109, 294.15 K)\n\n| Temperature delta  |   Room reference   |     Ice point      |   Absolute zero    |\n|====================|====================|====================|====================|\n| Lowest             |       -3 \u2103        |       18 \u2103        |     291.15 \u2103      |\n| Default            |        0 \u2103        |       21 \u2103        |     294.15 \u2103      |\n| Highest            |        3 \u2103        |       24 \u2103        |     297.15 \u2103      |\n
    "},{"location":"users_guide/framework_basics/the_affine_space/#no-text-output-for-points","title":"No text output for Points","text":"

    The library does not provide a text output for quantity points. The quantity stored inside is just an implementation detail of this type. It is a vector from a specific origin. Without the knowledge of the origin, the vector by itself is useless as we can't determine which point it describes.

    In the current library design, point origin does not provide any text in its definition. Even if we could add such information to the point's definition, we would not know how to output it in the text. There may be many ways to do it. For example, should we prepend or append the origin part to the quantity text?

    For example, the text output of 42 m for a quantity point may mean many things. It may be an offset from the mountain top, sea level, or maybe the center of Mars. Printing 42 m AMSL for altitudes above mean sea level is a much better solution, but the library does not have enough information to print it that way by itself.

    "},{"location":"users_guide/framework_basics/the_affine_space/#the-affine-space-is-about-type-safety","title":"The affine space is about type-safety","text":"

    The following operations are not allowed in the affine space:

    Important: The affine space improves safety

    The usage of quantity_point and affine space types, in general, improves expressiveness and type-safety of the code we write.

    "},{"location":"users_guide/framework_basics/value_conversions/","title":"Value Conversions","text":"

    One of the most important features of every unit library is to provide support for compile-time-enabled conversions of a numerical value of a quantity.

    A numerical value of a quantity depends on two elements:

    Changing any of the above may require changing the value stored in a quantity.

    "},{"location":"users_guide/framework_basics/value_conversions/#value-preserving-conversions","title":"Value-preserving conversions","text":"
    auto q1 = 5 * km;\nstd::cout << q1.in(m) << '\\n';\nquantity<si::metre, int> q2 = q1;\n

    The second line above converts the current quantity to the one expressed in meters and prints its contents. The third line converts the quantity expressed in kilometers into the one measured in meters.

    In case a user would like to perform an opposite transformation:

    auto q1 = 5 * m;\nstd::cout << q1.in(km) << '\\n';\nquantity<si::kilo<si::metre>, int> q2 = q1;\n

    Both conversions will fail to compile.

    There are two ways to make the above work. The first solution is to use a floating-point representation type:

    auto q1 = 5. * m;\nstd::cout << q1.in(km) << '\\n';\nquantity<si::kilo<si::metre>> q2 = q1;\n

    or

    auto q1 = 5 * m;\nstd::cout << value_cast<double>(q1).in(km) << '\\n';\nquantity<si::kilo<si::metre>> q2 = q1;  // double by default\n

    Important

    The mp-units library follows std::chrono::duration logic and treats floating-point types as value-preserving.

    "},{"location":"users_guide/framework_basics/value_conversions/#value-truncating-conversions","title":"Value-truncating conversions","text":"

    The second solution is to force a truncating conversion:

    auto q1 = 5 * m;\nstd::cout << value_cast<km>(q1) << '\\n';\nquantity<si::kilo<si::metre>, int> q2 = q1.force_in(km);\n

    This explicit cast makes it clear that something unsafe is going on. It is easy to spot in code reviews or while chasing a bug in the source code.

    Note

    q.force_in(U) is just a shortcut to run value_cast<U>(q). There is no difference in behavior between those two interfaces. q.force_in(U) was added for consistency with q.in(U) and q.force_numerical_value_in(U).

    Another place where this cast is useful is when a user wants to convert a quantity with a floating-point representation to the one using an integral one. Again, this is a truncating conversion, so an explicit cast is needed:

    quantity<si::metre, int> q3 = value_cast<int>(3.14 * m);\n

    Info

    It is often OK to use an integral as a representation type, but in general, floating-point types provide better precision and are privileged in the library as they are considered to be value-preserving.

    In some cases, a unit and a representation type should be changed simultaneously. Moreover, sometimes, the order of doing those operations matters. In such cases, the library provides the value_cast<U, Rep>(q) which always returns the most precise result:

    C++23C++20Portable 
    inline constexpr struct dim_currency final : base_dimension<\"$\"> {} dim_currency;\ninline constexpr struct currency final : quantity_spec<dim_currency> {} currency;\n\ninline constexpr struct us_dollar final : named_unit<\"USD\", kind_of<currency>> {} us_dollar;\ninline constexpr struct scaled_us_dollar final : named_unit<\"USD_s\", mag_power<10, -8> * us_dollar> {} scaled_us_dollar;\n\nnamespace unit_symbols {\n\ninline constexpr auto USD = us_dollar;\ninline constexpr auto USD_s = scaled_us_dollar;\n\n}  // namespace unit_symbols\n\nusing Price = quantity_point<currency[us_dollar]>;\nusing Scaled = quantity_point<currency[scaled_us_dollar], zeroth_point_origin<currency>, std::int64_t>;\n
    inline constexpr struct dim_currency final : base_dimension<\"$\"> {} dim_currency;\ninline constexpr struct currency final : quantity_spec<currency, dim_currency> {} currency;\n\ninline constexpr struct us_dollar final : named_unit<\"USD\", kind_of<currency>> {} us_dollar;\ninline constexpr struct scaled_us_dollar final : named_unit<\"USD_s\", mag_power<10, -8> * us_dollar> {} scaled_us_dollar;\n\nnamespace unit_symbols {\n\ninline constexpr auto USD = us_dollar;\ninline constexpr auto USD_s = scaled_us_dollar;\n\n}  // namespace unit_symbols\n\nusing Price = quantity_point<currency[us_dollar]>;\nusing Scaled = quantity_point<currency[scaled_us_dollar], zeroth_point_origin<currency>, std::int64_t>;\n
    inline constexpr struct dim_currency final : base_dimension<\"$\"> {} dim_currency;\nQUANTITY_SPEC(currency, dim_currency);\n\ninline constexpr struct us_dollar final : named_unit<\"USD\", kind_of<currency>> {} us_dollar;\ninline constexpr struct scaled_us_dollar final : named_unit<\"USD_s\", mag_power<10, -8> * us_dollar> {} scaled_us_dollar;\n\nnamespace unit_symbols {\n\ninline constexpr auto USD = us_dollar;\ninline constexpr auto USD_s = scaled_us_dollar;\n\n}  // namespace unit_symbols\n\nusing Price = quantity_point<currency[us_dollar]>;\nusing Scaled = quantity_point<currency[scaled_us_dollar], zeroth_point_origin<currency>, std::int64_t>;\n
    using namespace unit_symbols;\nPrice price{12.95 * USD};\nScaled spx = value_cast<USD_s, std::int64_t>(price);\n

    As a shortcut, instead of providing a unit and a representation type to value_cast, you may also provide a Quantity type directly, from which unit and representation type are taken. However, value_cast<Quantity>, still only allows for changes in unit and representation type, but not changing the type of the quantity. For that, you will have to use a quantity_cast instead.

    Overloads are also provided for instances of quantity_point. All variants of value_cast<...>(q) that apply to instances of quantity have a corresponding version applicable to quantity_point, where the point_origin remains untouched, and the cast changes how the \"offset\" from the origin is represented. Specifically, for any quantity_point instance qp, all of the following equivalences hold:

    static_assert(value_cast<Rep>(qp) == quantity_point{value_cast<Rep>(qp.quantity_from(qp.point_origin)), qp.point_origin});\nstatic_assert(value_cast<U>(qp) == quantity_point{value_cast<U>(qp.quantity_from(qp.point_origin)), qp.point_origin});\nstatic_assert(value_cast<U, Rep>(qp) == quantity_point{value_cast<U, Rep>(qp.quantity_from(qp.point_origin)), qp.point_origin});\nstatic_assert(value_cast<Q>(qp) == quantity_point{value_cast<Q>(qp.quantity_from(qp.point_origin)), qp.point_origin});\n

    Furthermore, there is one additional overload value_cast<ToQP>(qp). This overload permits to additionally replace the point_origin with another compatible one, while still representing the same point in the affine space. Thus, it is roughly equivalent to value_cast<ToQP::unit, ToQP::rep>(qp).point_for(ToQP::point_origin). In contrast to a separate value_cast followed by point_for (or vice-versa), the combined value_cast tries to choose the order of the individual conversion steps in a way to avoid both overflow and unnecessary loss of precision. Overflow is a risk because the change of origin point may require an addition of a potentially large offset (the difference between the origin points), which may well be outside the range of one or both quantity types.

    "},{"location":"users_guide/framework_basics/value_conversions/#scaling-overflow-prevention","title":"Scaling overflow prevention","text":"

    In the case of small integral types, it is easy to overflow the representation type for every value besides 0 while performing simple and popular unit conversions. This is why the library prevents such invalid conversions at compile-time both for explicit and implicit conversions:

    quantity q1 = std::int8_t(1) * km;\nquantity q2 = q1.force_in(m);   // Compile-time error (1)\nif(q1 != 1 * m) { /* ... */ }   // Compile-time error (2)\n
    1. Forced conversion would overflow on scaling.
    2. Implicit conversion that brings arguments to a common unit before comparison would overflow on scaling.

    In the above example, the conversion factor between km and m is 1'000, which is larger than the maximum value that can be stored in std::int8_t. Even if we want to convert the smallest possible integral amount (e.g., 1 km), we will overflow the quantity representation type. We decided not to allow such conversions for safety reasons despite the value of 0 km would work.

    "},{"location":"users_guide/framework_basics/value_conversions/#value-conversions-summary","title":"Value conversions summary","text":"

    The table below provides all the value conversion functions that may be run on x being the instance of either quantity or quantity_point:

    Forcing Representation Unit Member function Non-member function No Same u x.in(u) No T Same x.in<T>() No T u x.in<T>(u) Yes Same u x.force_in(u) value_cast<u>(x) Yes T Same x.force_in<T>() value_cast<T>(x) Yes T u x.force_in<T>(u) value_cast<u, T>(x) or value_cast<T, u>(x)"},{"location":"users_guide/systems/strong_angular_system/","title":"Strong Angular System","text":""},{"location":"users_guide/systems/strong_angular_system/#some-background-information","title":"Some background information","text":"

    As per today's SI, both radian and steradian are dimensionless. This forces the convention to set the angle 1 radian equal to the number 1 within equations (similar to what natural units system does for c constant).

    Following Wikipedia:

    Wikipedia: Radian - Dimensional analysis

    Giacomo Prando says \"the current state of affairs leads inevitably to ghostly appearances and disappearances of the radian in the dimensional analysis of physical equations.\" For example, a mass hanging by a string from a pulley will rise or drop by \\(y=r\u03b8\\) centimeters, where \\(r\\) is the radius of the pulley in centimeters and \\(\u03b8\\) is the angle the pulley turns in radians. When multiplying \\(r\\) by \\(\u03b8\\) the unit of radians disappears from the result. Similarly in the formula for the angular velocity of a rolling wheel, \\(\u03c9=v/r\\), radians appear in the units of \\(\u03c9\\) but not on the right hand side. Anthony French calls this phenomenon \"a perennial problem in the teaching of mechanics\". Oberhofer says that the typical advice of ignoring radians during dimensional analysis and adding or removing radians in units according to convention and contextual knowledge is \"pedagogically unsatisfying\".

    At least a dozen scientists have made proposals to treat the radian as a base unit of measure defining its own dimension of \"angle\", as early as 1936 and as recently as 2022. This would bring the advantages of a physics-based, consistent, and logically-robust unit system, with unambiguous units for all physical quantities. At the same time the only notable changes for typical end-users would be: improved units for the quantities torque, angular momentum, and moment of inertia.

    Paul Quincey in his proposal \"Angles in the SI: a detailed proposal for solving the problem\" states:

    Paul Quincey: Angles in the SI: a detailed proposal for solving the problem

    The familiar units assigned to some angular quantities are based on equations that have adopted the radian convention, and so are missing rads that would be present if the complete equation is used. The physically-correct units are those with the rads reinstated. Numerical values would not change, and the physical meanings of all quantities would also be unaffected.

    He proposes the following changes:

    Paul Quincey summarizes that with the above in action:

    Paul Quincey: Angles in the SI: a detailed proposal for solving the problem

    However, the physical clarity this would build into the SI should be recognised very quickly. The units would tell us that \\(torque \\times angle = energy\\), and \\(angular\\:momentum \\times angle = action\\), for example, in the same way that they do for \\(force \\times distance = energy\\), \\(linear\\:momentum \\times distance = action\\), and \\(radiant\\:intensity \\times solid\\:angle = radiant\\:flux\\). Dimensional analysis could be used to its full extent. Software involving angular quantities would be rationalised. Arguments about the correct units for frequency and angular frequency, and the meaning of the unit \\(Hz\\), could be left behind. The explanation of these changes would be considerably easier and more rewarding than explaining how a kilogram-sized mass can be measured in terms of the Planck constant.

    "},{"location":"users_guide/systems/strong_angular_system/#angular-quantities-in-the-si","title":"Angular quantities in the SI","text":"

    Even though the SI somehow ignores the dimensionality of angle:

    SI Brochure

    Plane and solid angles, when expressed in radians and steradians respectively, are in effect also treated within the SI as quantities with the unit one. The symbols \\(rad\\) and \\(sr\\) are written explicitly where appropriate, in order to emphasize that, for radians or steradians, the quantity being considered is, or involves the plane angle or solid angle respectively. For steradians it emphasizes the distinction between units of flux and intensity in radiometry and photometry for example. However, it is a long-established practice in mathematics and across all areas of science to make use of \\(rad = 1\\) and \\(sr = 1\\). For historical reasons the radian and steradian are treated as derived units.

    It also explicitly states:

    SI Brochure

    The SI unit of frequency is hertz, the SI unit of angular velocity and angular frequency is radian per second, and the SI unit of activity is becquerel, implying counts per second. Although it is formally correct to write all three of these units as the reciprocal second, the use of the different names emphasizes the different nature of the quantities concerned. It is especially important to carefully distinguish frequencies from angular frequencies, because by definition their numerical values differ by a factor of \\(2\\pi\\). Ignoring this fact may cause an error of \\(2\\pi\\). Note that in some countries, frequency values are conventionally expressed using \u201ccycle/s\u201d or \u201ccps\u201d instead of the SI unit \\(Hz\\), although \u201ccycle\u201d and \u201ccps\u201d are not units in the SI. Note also that it is common, although not recommended, to use the term frequency for quantities expressed in \\(rad/s\\). Because of this, it is recommended that quantities called \u201cfrequency\u201d, \u201cangular frequency\u201d, and \u201cangular velocity\u201d always be given explicit units of \\(Hz\\) or \\(rad/s\\) and not \\(s^{-1}\\).

    "},{"location":"users_guide/systems/strong_angular_system/#strong-angular-extensions-in-the-library","title":"Strong Angular extensions in the library","text":"

    The mp-units library strives to define physically-correct quantities and their units to provide maximum help to its users. As treating angle as a dimensional quantity can lead to many \"trivial\" mistakes in dimensional analysis and calculation, it was decided to provide additional experimental systems of quantities and units that follow the above approach and treat angle as a base quantity with a base unit of radian and solid angle as its derived quantity.

    As those (at least for now) are not a part of SI, the plain angle and solid angle definitions can be found in a dedicated angular system. Those definitions are also used in the isq_angle system of quantities to make the recipes for angle-based quantities like torque or angular velocity physically correct:

    using namespace mp_units;\nusing namespace mp_units::si::unit_symbols;\nusing mp_units::angular::unit_symbols::deg;\nusing mp_units::angular::unit_symbols::rad;\n\nconst quantity lever = isq_angle::position_vector(20 * cm);\nconst quantity force = isq_angle::force(500 * N);\nconst quantity angle = isq_angle::angular_measure(90. * deg);\nconst quantity torque = isq_angle::torque(lever * force * angular::sin(angle) / (1 * isq_angle::cotes_angle));\n\nstd::cout << \"Applying a perpendicular force of \" << force << \" to a \" << lever << \" long lever results in \"\n          << torque.in(N * m / rad) << \" of torque.\\n\";\n

    The above program prints:

    Applying a perpendicular force of 500 N to a 20 cm long lever results in 100 N m/rad of torque.\n

    Note

    cotes_angle is a constant which represents an angle with the value of exactly 1 radian. You can find more information about this constant in Quincey.

    Try it on Compiler Explorer

    "},{"location":"users_guide/use_cases/interoperability_with_other_libraries/","title":"Interoperability with Other Libraries","text":"

    mp-units makes it easy to cooperate with similar entities of other libraries. No matter if we want to provide interoperability with a simple home-grown strongly typed wrapper type (e.g., Meter, Timestamp, ...) or with a feature-rich quantities and units library, we have to provide specializations of:

    "},{"location":"users_guide/use_cases/interoperability_with_other_libraries/#specifying-a-conversion-kind","title":"Specifying a conversion kind","text":"

    Before we delve into the template specialization details, let's first decide if we want the conversions to happen implicitly or if explicit ones would be a better choice. Or maybe the conversion should be implicit in one direction only (e.g., into mp-units abstractions) while the explicit conversions in the other direction should be preferred?

    There is no one unified answer to the above questions. Everything depends on the use case.

    Typically, the implicit conversions are allowed in cases where:

    In all other scenarios, we should probably enforce explicit conversions.

    The kinds of inter-library conversions can be easily configured in partial specializations of conversion traits in the mp-units library. Conversion traits should provide a static data member convertible to bool. If the value is true, then the conversion is explicit. Otherwise, if the value is false, implicit conversions will be allowed. The names of the flags are as follows:

    "},{"location":"users_guide/use_cases/interoperability_with_other_libraries/#quantities-conversions","title":"Quantities conversions","text":"

    For example, let's assume that some company has its own Meter strong-type wrapper:

    struct Meter {\n  int value;\n};\n

    As every usage of Meter is at least as good and safe as the usage of quantity<si::metre, int>, and as there is no significant runtime performance penalty, we would like to allow the conversion to mp_units::quantity to happen implicitly.

    On the other hand, the quantity type is much safer than the Meter, and that is why we would prefer to see the opposite conversions stated explicitly in our code.

    To enable such interoperability, we must define a partial specialization of the quantity_like_traits<T> type trait. Such specialization should provide:

    For example, for our Meter type, we could provide the following:

    template<>\nstruct mp_units::quantity_like_traits<Meter> {\n  static constexpr auto reference = si::metre;\n  static constexpr bool explicit_import = false;\n  static constexpr bool explicit_export = true;\n  using rep = decltype(Meter::value);\n  static constexpr rep to_numerical_value(Meter m) { return m.value; }\n  static constexpr Meter from_numerical_value(rep v) { return Meter{v}; }\n};\n

    After that, we can check that the QuantityLike concept is satisfied:

    static_assert(mp_units::QuantityLike<Meter>);\n

    and we can write the following:

    void print(Meter m) { std::cout << m.value << \" m\\n\"; }\n\nint main()\n{\n  using namespace mp_units;\n  using namespace mp_units::si::unit_symbols;\n\n  Meter height{42};\n\n  // implicit conversions\n  quantity h1 = height;\n  quantity<isq::height[m], int> h2 = height;\n\n  std::cout << h1 << \"\\n\";\n  std::cout << h2 << \"\\n\";\n\n  // explicit conversions\n  print(Meter(h1));\n  print(Meter(h2));\n}\n

    Note

    No matter if we decide to use implicit or explicit conversions, the mp-units will not allow unsafe operations to happen.

    If we extend the above example with unsafe conversions, the code will not compile, and we will have to fix the issues first before the conversion may be performed:

    UnsafeFixed 
    quantity<isq::height[m]> h3 = height;\nquantity<isq::height[mm], int> h4 = height;\nquantity<isq::height[km], int> h5 = height;  // Compile-time error (1)\n\nstd::cout << h3 << \"\\n\";\nstd::cout << h4 << \"\\n\";\nstd::cout << h5 << \"\\n\";\n\nprint(Meter(h3));                            // Compile-time error (2)\nprint(Meter(h4));                            // Compile-time error (3)\nprint(Meter(h5));\n
    1. Truncation of value while converting from meters to kilometers.
    2. Conversion of double to int is not value-preserving.
    3. Truncation of value while converting from millimeters to meters.
    quantity<isq::height[m]> h3 = height;\nquantity<isq::height[mm], int> h4 = height;\nquantity<isq::height[km], int> h5 = quantity{height}.force_in(km);\n\nstd::cout << h3 << \"\\n\";\nstd::cout << h4 << \"\\n\";\nstd::cout << h5 << \"\\n\";\n\nprint(Meter(value_cast<int>(h3)));\nprint(Meter(h4.force_in(m)));\nprint(Meter(h5));\n
    "},{"location":"users_guide/use_cases/interoperability_with_other_libraries/#quantity-points-conversions","title":"Quantity points conversions","text":"

    To play with quantity point conversions, let's assume that we have a Timestamp strong type in our codebase, and we would like to start using mp-units to work with this abstraction.

    struct Timestamp {\n  int seconds;\n};\n

    As we described in The Affine Space chapter, timestamps should be modeled as quantity points rather than regular quantities.

    To allow the conversion between our custom Timestamp type and the quantity_point class template we need to provide the following in the partial specialization of the quantity_point_like_traits<T> type trait:

    For example, for our Timestamp type, we could provide the following:

    template<>\nstruct mp_units::quantity_point_like_traits<Timestamp> {\n  static constexpr auto reference = si::second;\n  static constexpr auto point_origin = default_point_origin(reference);\n  static constexpr bool explicit_import = false;\n  static constexpr bool explicit_export = true;\n  using rep = decltype(Timestamp::seconds);\n  static constexpr rep to_numerical_value(Timestamp ts) { return ts.seconds; }\n  static constexpr Timestamp from_numerical_value(rep v) { return Timestamp(v); }\n};\n

    After that, we can check that the QuantityPointLike concept is satisfied:

    static_assert(mp_units::QuantityPointLike<Timestamp>);\n

    and we can write the following:

    void print(Timestamp ts) { std::cout << ts.seconds << \" s\\n\"; }\n\nint main()\n{\n  using namespace mp_units;\n  using namespace mp_units::si::unit_symbols;\n\n  Timestamp ts{42};\n\n  // implicit conversion\n  quantity_point qp = ts;\n\n  std::cout << qp.quantity_from_zero() << \"\\n\";\n\n  // explicit conversion\n  print(Timestamp(qp));\n}\n
    "},{"location":"users_guide/use_cases/interoperability_with_other_libraries/#interoperability-with-the-c-standard-library","title":"Interoperability with the C++ Standard Library","text":"

    In the C++ standard library, we have two types that handle quantities and model the affine space. Those are:

    The mp-units library comes with built-in interoperability with those types. It is enough to include the mp-units/systems/si/chrono.h file to benefit from it. This file provides:

    Important

    Only a quantity_point that uses chrono_point_origin<Clock> as its origin can be converted to the std::chrono abstractions:

    inline constexpr struct ts_origin final : relative_point_origin<chrono_point_origin<system_clock> + 1 * h> {} ts_origin;\ninline constexpr struct my_origin final : absolute_point_origin<isq::time> {} my_origin;\n\nquantity_point qp1 = sys_seconds{1s};\nauto tp1 = to_chrono_time_point(qp1);  // OK\n\nquantity_point qp2 = chrono_point_origin<system_clock> + 1 * s;\nauto tp2 = to_chrono_time_point(qp2);  // OK\n\nquantity_point qp3 = ts_origin + 1 * s;\nauto tp3 = to_chrono_time_point(qp3);  // OK\n\nquantity_point qp4 = my_origin + 1 * s;\nauto tp4 = to_chrono_time_point(qp4);  // Compile-time Error (1)\n\nquantity_point qp5{1 * s};\nauto tp5 = to_chrono_time_point(qp5);  // Compile-time Error (2)\n
    1. my_origin is not defined in terms of chrono_point_origin<Clock>.
    2. zeroth_point_origin is not defined in terms of chrono_point_origin<Clock>.

    Here is an example of how interoperability described in this chapter can be used in practice:

    using namespace std::chrono;\n\nsys_seconds ts_now = floor<seconds>(system_clock::now());\n\nquantity_point start_time = ts_now;\nquantity speed = 925. * km / h;\nquantity distance = 8111. * km;\nquantity flight_time = distance / speed;\nquantity_point exp_end_time = start_time + flight_time;\n\nsys_seconds ts_end = value_cast<int>(exp_end_time.in(s));\n\nauto curr_time = zoned_time(current_zone(), ts_now);\nauto mst_time = zoned_time(\"America/Denver\", ts_end);\n\nstd::cout << \"Takeoff: \" << curr_time << \"\\n\";\nstd::cout << \"Landing: \" << mst_time << \"\\n\";\n

    The above may print the following output:

    Takeoff: 2023-11-18 13:20:54 UTC\nLanding: 2023-11-18 15:07:01 MST\n
    "},{"location":"users_guide/use_cases/wide_compatibility/","title":"Wide Compatibility","text":"

    The mp-units allows us to implement nice and terse code targeting a specific C++ version and configuration. Such code is easy to write and understand but might not be portable to some older environments.

    However, sometimes, we want to develop code that can be compiled on a wide range of various compilers and configurations. This is why the library also exposes and uses special preprocessor macros that can be used to ensure the wide compatibility of our code.

    Note

    Those macros are used in our short example applications as those are meant to be built on all of the supported compilers. Some still do not support std::format, C++ modules, or C++ versions newer than C++20.

    "},{"location":"users_guide/use_cases/wide_compatibility/#various-compatibility-options","title":"Various compatibility options","text":"

    Depending on your compiler's conformance, you can choose to use any of the below styles to write your code using mp-units:

    C++23C++20C++20 with header filesC++20 with header files + libfmtWide Compatibility 
    #include <format>\n#include <iostream>\nimport mp_units;\n\n// ...\n\ninline constexpr struct horizontal_length final : quantity_spec<isq::length> {} horizontal_length;\n\n// ...\n\nstd::cout << std::format(...) << \"\\n\";\n
    #include <format>\n#include <iostream>\nimport mp_units;\n\n// ...\n\ninline constexpr struct horizontal_length final : quantity_spec<horizontal_length, isq::length> {} horizontal_length;\n\n// ...\n\nstd::cout << std::format(...) << \"\\n\";\n
    #include <mp-units/systems/international.h>\n#include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n#include <format>\n#include <iostream>\n\n// ...\n\ninline constexpr struct horizontal_length final : quantity_spec<horizontal_length, isq::length> {} horizontal_length;\n\n// ...\n\nstd::cout << std::format(...) << \"\\n\";\n
    #include <mp-units/systems/international.h>\n#include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n#include <fmt/format.h>\n#include <iostream>\n\n// ...\n\ninline constexpr struct horizontal_length final : quantity_spec<horizontal_length, isq::length> {} horizontal_length;\n\n// ...\n\nstd::cout << fmt::format(...) << \"\\n\";\n
    #include <iostream>\n#include <mp-units/ext/format.h>\n#ifdef MP_UNITS_MODULES\n#include <mp-units/compat_macros.h>\nimport mp_units;\n#else\n#include <mp-units/systems/international.h>\n#include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n#endif\n\n// ...\n\nQUANTITY_SPEC(horizontal_length, isq::length);\n\n// ...\n\nstd::cout << MP_UNITS_STD_FMT::format(...) << \"\\n\";\n

    Tip

    Depending on your preferences, you can either write:

    "},{"location":"users_guide/use_cases/wide_compatibility/#compatibility-macros","title":"Compatibility macros","text":"

    This chapter describes only the most essential tools the mp-units users need. All the compatibility macros can be found in the mp-units/compat_macros.h header file.

    Tip

    The mp-units/compat_macros.h header file is implicitly included when we use \"legacy\" headers in our translation units. However, it has to be explicitly included when we use C++20 modules, as those do not propagate preprocessor macros.

    "},{"location":"users_guide/use_cases/wide_compatibility/#QUANTITY_SPEC","title":"QUANTITY_SPEC(name, ...)","text":"

    Quantity specification definitions benefit from an explicit object parameter added in C++23 to remove the need for CRTP idiom, which significantly simplifies the code.

    This macro benefits from the new C++23 feature if available. Otherwise, it uses the CRTP idiom under the hood.

    "},{"location":"users_guide/use_cases/wide_compatibility/#mp_units_std_fmt","title":"MP_UNITS_STD_FMT","text":"

    Some of the supported compilers do not support std::format and related tools. Also, despite using a conformant compiler, some projects still choose to use fmtlib as their primary formatting facility (e.g., to benefit from additional features provided with the library).

    This macro resolves to either the std or fmt namespace, depending on the value of MP_UNITS_API_STD_FORMAT CMake option.

    To include the header files of the underlying text formatting framework, the following include should be used:

    #include <mp-units/ext/format.h>\n
    "},{"location":"users_guide/use_cases/wide_compatibility/#contracts","title":"Contracts","text":"

    The mp-units library internally does contract checking by default. It can be disabled with a Conan or CMake option. However, when enabled, it can use either gsl-lite or ms-gsl. To write a code that is independent from the underlying framework, the following preprocessor macros are exposed:

    Their meaning is consistent with respective gsl-lite.

    Also, to include the header files of the underlying framework, the following include should be used:

    #include <mp-units/ext/contracts.h>\n
    "},{"location":"users_guide/use_cases/working_with_legacy_interfaces/","title":"Working with Legacy interfaces","text":"

    In case we are working with a legacy/unsafe interface, we may need to extract the numerical value of a quantity and pass it to some third-party legacy unsafe interfaces.

    In such situations we can use .numerical_value_in(Unit) member function:

    void legacy_check_speed_limit(int speed_in_km_per_h);\n
    legacy_check_speed_limit((180 * km / (2 * h)).numerical_value_in(km / h));\n

    Such a getter will explicitly enforce the usage of a correct unit required by the underlying interface, which reduces a significant number of safety-related issues.

    The above code will not compile in case value truncation may happen. To solve the issue, we need to either use a value-preserving representation type or force the truncating conversion with .force_numerical_value_in(Unit):

    legacy_check_speed_limit((140 * mi / (2 * h)).force_numerical_value_in(km / h));\n

    The getters mentioned above always return by value as a quantity value conversion may be required to adjust it to the target unit. In case a user needs a reference to the underlying storage .numerical_value_ref_in(Unit) should be used:

    void legacy_set_speed_limit(int* speed_in_km_per_h) { *speed_in_km_per_h = 100; }\n
    quantity<km / h, int> speed_limit;\nlegacy_set_speed_limit(&speed_limit.numerical_value_ref_in(km / h));\n

    This member function again requires a target unit to enforce safety. This overload does not participate in overload resolution if the provided unit has a different scaling factor than the current one.

    "},{"location":"blog/archive/2025/","title":"2025","text":""},{"location":"blog/archive/2024/","title":"2024","text":""},{"location":"blog/archive/2023/","title":"2023","text":""},{"location":"blog/category/metrology/","title":"Metrology","text":""},{"location":"blog/category/wg21-updates/","title":"WG21 Updates","text":""},{"location":"blog/category/releases/","title":"Releases","text":""},{"location":"blog/page/2/","title":"Blog","text":""},{"location":"blog/archive/2024/page/2/","title":"2024","text":""}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome to mp-units!","text":"

    mp-units is a compile-time enabled feature-rich Modern C++ modular/header-only library that provides compile-time dimensional analysis and unit/quantity manipulation. Its key strengths include safety, performance, and developer experience.

    It is the first library on the market that, besides being unit-safe and dimension-safe, is also quantity-safe.

    The library source code is hosted on GitHub with a permissive MIT license.

    Supported compilers

    This library tries to provide the best user experience possible with the C++ language. To achieve that, it extensively uses the latest C++ language features.

    Even though the library benefits from the latest C++ versions (if available), C++20 is enough to compile and use all of the library's functionality.

    Please refer to C++ compiler support chapter for more details.

    C++ modulesHeader files 
    #include <iostream>\n#include <print>\nimport mp_units;\n\nusing namespace mp_units;\n\ninline constexpr struct smoot final : named_unit<\"smoot\", mag<67> * usc::inch> {} smoot;\n\nint main()\n{\n  constexpr quantity dist = 364.4 * smoot;\n  std::println(\"Harvard Bridge length = {::N[.1f]} ({::N[.1f]}, {::N[.2f]}) \u00b1 1 \u03b5ar\",\n               dist, dist.in(usc::foot), dist.in(si::metre));\n}\n
    #include <mp-units/systems/si.h>\n#include <mp-units/systems/usc.h>\n#include <print>\n\nusing namespace mp_units;\n\ninline constexpr struct smoot final : named_unit<\"smoot\", mag<67> * usc::inch> {} smoot;\n\nint main()\n{\n  constexpr quantity dist = 364.4 * smoot;\n  std::println(\"Harvard Bridge length = {::N[.1f]} ({::N[.1f]}, {::N[.2f]}) \u00b1 1 \u03b5ar\",\n               dist, dist.in(usc::foot), dist.in(si::metre));\n}\n

    Output:

    Harvard Bridge length = 364.4 smoot (2034.6 ft, 620.14 m) \u00b1 1 \u03b5ar\n

    Try it on Compiler Explorer

    What is smoot?

    The smoot (/\u02c8smu\u02d0t/) is a nonstandard unit of length created as part of an MIT fraternity prank. It is named after Oliver R. Smoot, a fraternity pledge to Lambda Chi Alpha, who, in October 1958, lay on the Harvard Bridge (between Boston and Cambridge, Massachusetts) and was used by his fraternity brothers to measure the length of the bridge.

    One smoot equals Oliver Smoot's height at the time of the prank (five feet and seven inches). The bridge's length was measured to be 364.4 smoots plus or minus one ear, with the \"plus or minus\" intended to express the measurement uncertainty.

    Oliver Smoot graduated from MIT with the class of 1962, became a lawyer, and later became chairman of the American National Standards Institute (ANSI) and president of the International Organization for Standardization (ISO).

    More on the smoot unit of length can be found at https://en.wikipedia.org/wiki/Smoot.

    Important: Help needed!

    The mp-units library might be the subject of ISO standardization for C++29. More on this can be found in the following ISO C++ proposals:

    We are actively looking for parties interested in field-trialing the library.

    "},{"location":"api_reference/","title":"API Reference - mp-units","text":""},{"location":"release_notes/","title":"Release Notes","text":""},{"location":"release_notes/#mp-units","title":"mp-units","text":""},{"location":"release_notes/#2.5.0","title":"2.5.0 WIP","text":""},{"location":"release_notes/#2.4.0","title":"2.4.0 November 5, 2024","text":""},{"location":"release_notes/#2.3.0","title":"2.3.0 September 27, 2024","text":""},{"location":"release_notes/#2.2.1","title":"2.2.1 July 3, 2024","text":""},{"location":"release_notes/#2.2.0","title":"2.2.0 June 14, 2024","text":""},{"location":"release_notes/#2.1.1","title":"2.1.1 May 16, 2024","text":""},{"location":"release_notes/#2.1.0","title":"2.1.0 December 9, 2023","text":""},{"location":"release_notes/#2.0.0","title":"2.0.0 September 24, 2023","text":""},{"location":"release_notes/#0.8.0","title":"0.8.0 June 14, 2023","text":""},{"location":"release_notes/#0.7.0","title":"0.7.0 May 11, 2021","text":""},{"location":"release_notes/#0.6.0","title":"0.6.0 September 13, 2020","text":""},{"location":"release_notes/#0.5.0","title":"0.5.0 May 17, 2020","text":"

    Many thanks to GitHub users @oschonrock, @kwikius, and @i-ky for their support in drafting a new library design.

    "},{"location":"release_notes/#0.4.0","title":"0.4.0 Nov 17, 2019","text":""},{"location":"release_notes/#0.3.1","title":"0.3.1 Sep 18, 2019","text":""},{"location":"release_notes/#0.3.0","title":"0.3.0 Sep 16, 2019","text":""},{"location":"release_notes/#0.2.0","title":"0.2.0 July 18, 2019","text":""},{"location":"release_notes/#0.1.0","title":"0.1.0 May 18, 2019","text":""},{"location":"appendix/glossary/","title":"Glossary","text":""},{"location":"appendix/glossary/#iso-definitions","title":"ISO definitions","text":"

    Note

    The ISO terms provided below are only a few of many defined in the ISO/IEC Guide 99.

    quantity kind of quantity, kind system of quantities base quantity derived quantity International System of Quantities, ISQ quantity dimension, dimension of a quantity, dimension quantity of dimension one, dimensionless quantity measurement unit, unit of measurement, unit base unit derived unit coherent derived unit system of units coherent system of units off-system measurement unit, off-system unit International System of Units, SI quantity value, value of a quantity, value numerical quantity value, numerical value of a quantity, numerical value quantity equation unit equation numerical value equation, numerical quantity value equation "},{"location":"appendix/glossary/#other-definitions","title":"Other definitions","text":"

    Info

    The below terms extend the official ISO glossary and are commonly referred to by the mp-units library.

    base dimension derived dimension dimension equation quantity kind hierarchy, quantity hierarchy quantity character, character of a quantity, character

    ISO 80000-1_2009

    In deriving the dimension of a quantity, no account is taken of its scalar, vector, or tensor character.

    quantity specification, quantity_spec unit with an associated quantity, associated unit quantity reference, reference canonical representation of a unit, canonical unit reference unit

    See canonical representation of a unit

    absolute quantity point origin, absolute point origin relative quantity point origin, relative point origin quantity point origin, point origin quantity point, absolute quantity "},{"location":"appendix/references/","title":"References","text":"ISO80000

    ISO 80000-1:2009(E) \"Quantities and units \u2014 Part 1: General\", International Organization for Standardization.

    Quincey \"Angles in the SI: a detailed proposal for solving the problem, Quincey, Paul (1 October 2021). SIBrochure

    The International System of Units (SI), International Bureau of Weights and Measures (20 May 2019), ISBN 978-92-822-2272-0.

    "},{"location":"blog/","title":"Blog","text":""},{"location":"blog/2023/09/24/whats-new-in-mp-units-20/","title":"What's new in mp-units 2.0?","text":"

    After a year of hard work, we've just released mp-units 2.0.0. It can be obtained from GitHub and Conan.

    The list of the most significant changes introduced by the new version can be found in our Release Notes. We will also describe some of them in this post.

    "},{"location":"blog/2023/09/24/whats-new-in-mp-units-20/#why-20-if-10-was-never-released","title":"Why 2.0 if 1.0 was never released?","text":"

    Version 2 of the mp-units project is a huge change and a new quality for the users. We did not want to pretend that 2.0 is an evolutionary upgrade of the previous version of the project. It feels like a different product.

    We could start a new repo named \"mp-units-v2\" similarly to range-v3 but we decided not to go this path. We kept the same repo and made the scope of the changes and potential breakage explicit with a drastic bump in the project version.

    "},{"location":"blog/2023/09/24/whats-new-in-mp-units-20/#what-has-changed","title":"What has changed?","text":"

    The answer is \"nearly everything\". The whole library and its documentation were rewritten nearly from scratch.

    Here are the significant changes that the users can observe:

    "},{"location":"blog/2023/09/24/whats-new-in-mp-units-20/#what-is-gone","title":"What is gone?","text":"

    Some cornerstones of the initial design did not prove in practice and were removed while we moved to version 2.

    "},{"location":"blog/2023/09/24/whats-new-in-mp-units-20/#the-downcasting-facility","title":"The downcasting facility","text":"

    The first and the most important of such features was removing the downcasting facility. This feature is still a powerful metaprogramming technique that allows users to map long class template instantiations to nicely named, short, and easy-to-understand user's strong types.

    Such mapping works perfectly fine for 1-to-1 relationships. However, we often deal with N-to-1 connections in the quantities and units domain. Here are only a few such examples:

    In the above examples, multiple entities \"wanted\" to register different names for identical class template instantiations, resulting in compile-time errors. We had to invent some hacks and workarounds to make it work, but we were never satisfied with the outcome.

    Additionally, this facility could easily lead to ODR violations or provide different results depending on which header files were included in the translation units. This was too vulnerable to be considered a good practice here.

    "},{"location":"blog/2023/09/24/whats-new-in-mp-units-20/#no-udls-anymore","title":"No UDLs anymore","text":"

    Over the years, we have learned that UDLs are not a good solution. More information on this subject can be found in the Why don't we use UDLs to create quantities? chapter.

    "},{"location":"blog/2023/09/24/whats-new-in-mp-units-20/#no-construction-of-a-quantity-from-a-raw-value","title":"No construction of a quantity from a raw value","text":"

    To improve safety, we no longer allow the construction of quantities from raw values. In the new design, we always need to explicitly specify a unit to create a quantity:

    quantity q1 = 42 * m;\nquantity<si::metre> = 2 * km;\nquantity q3(42, si::metre);\n

    The previous approach was reported to be error-prone under maintenance. More on this subject can be found in the Why can't I create a quantity by passing a number to a constructor? chapter.

    "},{"location":"blog/2023/09/24/whats-new-in-mp-units-20/#new-look-and-feel","title":"New look and feel","text":"

    Here is a concise example showing you the new look and feel of the library:

    #include <mp-units/format.h>\n#include <mp-units/systems/isq/isq.h>\n#include <mp-units/systems/si/si.h>\n#include <format>\n\nusing namespace mp_units;\nusing namespace mp_units::si::unit_symbols;\n\nquantity<isq::speed[m / s]> avg_speed(quantity<si::metre> d,\n                                      quantity<si::second> t)\n{ return d / t; }\n\nint main()\n{\n  auto speed = avg_speed(220 * km, 2 * h);\n  std::println(\"{}\", speed);  // 30.5556 m/s\n}\n

    All of the changes we provided, although breaking ones, resulted in much better, easier, and safer abstractions. These offer a new quantity on the market and hopefully will be appreciated by our users.

    Please check our new documentation to learn about the latest version of the project and find out how to benefit from all the new cool stuff we have here.

    "},{"location":"blog/2023/12/09/mp-units-210-released/","title":"mp-units 2.1.0 released!","text":"

    A new product version can be obtained from GitHub and Conan.

    The list of the most significant changes introduced by the new version can be found in our Release Notes. We will also describe the most important of them in this post.

    "},{"location":"blog/2023/12/09/mp-units-210-released/#no-more-parenthesis-while-creating-quantities-with-derived-units","title":"No more parenthesis while creating quantities with derived units","text":"

    The V2 design introduced a way to create a quantity by multiplying a raw value and a unit:

    quantity q1 = 42 * m;\n

    However, this meant that when we wanted to create a quantity having a derived unit, we had to put parenthesis around the unit equation or create a custom value of the named unit:

    quantity q2 = 60 * (km / h);\n\nconstexpr auto kmph = km / h;\nquantity q3 = 60 * kmph;\n\nquantity q4 = 50 * (1 / s);\n

    With the new version, we removed this restriction, and now we can type:

    quantity q5 = 60 * km / h;\nquantity q6 = 50 / s;\n

    As a side effect, we introduced a breaking change . We can't use the following definition of hertz anymore:

    inline constexpr struct hertz : named_unit<\"Hz\", 1 / second, kind_of<isq::frequency>> {} hertz;\n

    and have to type either:

    inline constexpr struct hertz : named_unit<\"Hz\", one / second, kind_of<isq::frequency>> {} hertz;\n

    or

    inline constexpr struct hertz : named_unit<\"Hz\", inverse(second), kind_of<isq::frequency>> {} hertz;\n

    To be consistent, we applied the same change to the dimensions and quantity specifications definitions. Now, to define a frequency we have to type:

    C++23C++20Portable 
    inline constexpr struct frequency : quantity_spec<inverse(period_duration)> {} frequency;\n
    inline constexpr struct frequency : quantity_spec<frequency, inverse(period_duration)> {} frequency;\n
    QUANTITY_SPEC(frequency, inverse(period_duration));\n
    "},{"location":"blog/2023/12/09/mp-units-210-released/#make_xxx-factory-functions-replaced-with-two-parameter-constructors","title":"make_xxx factory functions replaced with two-parameter constructors","text":"

    In the initial version of the V2 framework, if someone did not like the multiply syntax to create a quantity we provided the make_quantity() factory function. A similar approach was used for quantity_point creation.

    This version removes those ( breaking change ) and introduces two parameter constructors:

    quantity q(42, si::metre);\nquantity_point qp(q, mean_sea_level);\n

    The above change encourages a better design and results in a terser code.

    "},{"location":"blog/2023/12/09/mp-units-210-released/#improved-definitions-of-becquerel-gray-and-sievert","title":"Improved definitions of becquerel, gray, and sievert","text":"

    In the initial V2 version, we lacked the definitions of the atomic and nuclear physics quantities, which resulted in simplified and unsafe definitions of becquerel, gray, and sievert units. We still do not model most of the quantities from this domain, but we've added the ones that are necessary for the definition of those units.

    Thanks to the above, the following expressions will not compile:

    quantity q1 = 1 * Hz + 1 * Bq;\nquantity<si::sievert> q2 = 42 * Gy;\n
    "},{"location":"blog/2023/12/09/mp-units-210-released/#compatibility-with-other-libraries-redesigned","title":"Compatibility with other libraries redesigned","text":"

    Another significant improvement in this version was redesigning the way we provide compatibility with other similar libraries. The interfaces of quantity_like_traits and quantity_point_like_traits were changed and extended to provide conversion not only from but also to entities from other libraries ( breaking change ).

    We've also introduced an innovative approach that allows us to specify if such conversions should happen implicitly or if they need to be forced explicitly.

    More on this subject can be found in the Interoperability with Other Libraries chapter.

    "},{"location":"blog/2023/12/09/mp-units-210-released/#point-origins-can-now-be-derived-from-each-other","title":"Point origins can now be derived from each other","text":"

    Previously, each class derived from absolute_point_origin was considered a unique independent point origin. On the other hand, it was OK to derive multiple classes from the same relative_point_origin, and those were specifying the same point in the domain. We found this confusing and limiting. This is why, in this version, the absolute_point_origin uses a CRTP idiom to be able to detect between points that should be considered different from the ones that should be equivalent.

    If we derive from the same instantiation of absolute_point_origin we end up with an equivalent point origin. This change allows us to provide different names for the same temperature points:

    inline constexpr struct absolute_zero : absolute_point_origin<absolute_zero, isq::thermodynamic_temperature> {} absolute_zero;\ninline constexpr struct zeroth_kelvin : decltype(absolute_zero) {} zeroth_kelvin;\n\ninline constexpr struct ice_point : relative_point_origin<absolute_zero + 273.15 * kelvin> {} ice_point;\ninline constexpr struct zeroth_degree_Celsius : decltype(ice_point) {} zeroth_degree_Celsius;\n

    Please note that this is a breaking change as well.

    "},{"location":"blog/2023/12/09/mp-units-210-released/#unit-symbol-text-can-now-be-properly-used-at-runtime","title":"Unit symbol text can now be properly used at runtime","text":"

    The interface of the previous definition of unit_symbol function allowed the use of the returned buffer only at compile-time. This was too limiting as users often want to use unit symbols at runtime (e.g., print them to the console). The new version redesigned the interface of this function ( breaking change ) to return a buffer that can be properly used at both compilation and runtime:

    std::string_view unit1 = unit_symbol(m / s);\nstd::cout << unit1 << \"\\n\";     // m/s\nstd::string_view unit2 = unit_symbol<{.solidus = unit_symbol_solidus::never}>(m / s);\nstd::cout << unit2 << \"\\n\";     // m s\u207b\u00b9\n
    "},{"location":"blog/2024/06/14/mp-units-220-released/","title":"mp-units 2.2.0 released!","text":"

    A new product version can be obtained from GitHub and Conan.

    Among other features, this release provides long-awaited support for C++20 modules, redesigns and enhances text output formatting, and greatly simplifies quantity point usage. This post describes those and a few other smaller interesting improvements, while a much longer list of the most significant changes introduced by the new version can be found in our Release Notes.

    "},{"location":"blog/2024/06/14/mp-units-220-released/#c20-modules-and-project-structure-cleanup","title":"C++20 modules and project structure cleanup","text":"

    GitHub Issue #7 was our oldest open issue before this release. Not anymore. After 4.5 years, we finally closed it, even though the C++ modules' support is still really limited.

    Info

    To benefit from C++ modules, we need at least:

    In the upcoming months, hopefully, the situation will improve with the bug fixes in CMake, gcc-14, and MSVC.

    Note

    More requirements for C++ modules support can be found in the CMake's documentation.

    To enable the compilation and distribution of C++ modules, a cxx_modules Conan or MP_UNITS_BUILD_CXX_MODULES CMake option has to be enabled.

    With the above, the following C++ modules will be provided:

    flowchart TD\n    mp_units --- mp_units.systems --- mp_units.core
    C++ Module CMake Target Contents mp_units.core mp-units::core Core library framework and systems-independent utilities mp_units.systems mp-units::systems All the systems of quantities and units mp_units mp-units::mp-units Core + Systems

    The easiest way to use them is just to import mp_units; at the beginning of your translation unit (see the Quick Start chapter for some usage examples).

    Note

    C++20 modules support still have some issues when imported from the installed CMake target. See the following GitLab issue for more details.

    In this release, we also highly limited the number of CMake targets ( breaking change ). Now, they correspond exactly to the C++ modules they provide. This means that many smaller partial targets were removed. We also merged text output targets with the core library's definition.

    The table below specifies where we can now find the contents of previously available CMake targets:

    Before Now mp-units::utility mp-units::core mp-units::core-io mp-units::core mp-units::core-fmt mp-units::core mp-units::{system_name} mp-units::systems

    While we were enabling C++ modules, we also had to refactor our header files slightly ( breaking change ). Some had to be split into smaller pieces (e.g., math.h), while others had to be moved to a different subdirectory (e.g., chrono.h).

    In version 2.2, the following headers have a new location or contents:

    Header File C++ Module Contents mp-units/math.h mp_units.core System-independent functions only mp-units/systems/si/math.h mp_units.systems Trigonometric functions using si::radian mp-units/systems/angular/math.h mp_units.systems Trigonometric functions using angular::radian mp-units/systems/si/chrono.h mp_units.systems std::chrono compatibility traits

    Benefiting from this opportunity, we also cleaned up core and systems definitions ( breaking change ).

    Regarding the library's core, we removed core.h and exposed only one header framework.h that provides all of the library's framework so the user does not have to enumerate files like unit.h, quantity.h, and quantity_point.h anymore. Those headers are not gone, they were put to the mp-units/framework subheader. So they are still there if you really need them.

    Regarding the changes in systems definitions, we moved the wrapper header files with the entire system definition to the mp-units/systems subdirectory. Additionally, they now also include framework.h, so a system include is enough to use the library. Thanks to that our users don't have to write tedious code like the below anymore:

    NowBefore 
    #include <mp-units/systems/cgs.h>\n#include <mp-units/systems/international.h>\n#include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n\n// ...\n
    #include <mp-units/quantity_point.h>\n#include <mp-units/systems/cgs/cgs.h>\n#include <mp-units/systems/international/international.h>\n#include <mp-units/systems/isq/isq.h>\n#include <mp-units/systems/si/si.h>\n\n// ...\n

    Additionally, we merged all of the compatibility-related macros into one header file mp-units/compat_macros.h. This header file should be explicitly included before importing C++ modules if we want to benefit from the Wide Compatibility tools.

    "},{"location":"blog/2024/06/14/mp-units-220-released/#better-control-over-the-librarys-api","title":"Better control over the library's API","text":"

    With this release, nearly all of the Conan and CMake build options were refactored with the intent of providing better control over the library's API.

    Previously, the library used the latest available feature set supported by a specific compiler. For example, quantity_spec definitions would use CRTP on an older compiler or provide a simpler API on a newer one thanks to the C++23 this deduction feature. This could lead to surprising results where the same code written by the user would compile fine on one compiler but not the other.

    From this release, all API extensions have their corresponding configuration options in Conan and CMake. With this, a user has full control over the API exposed by the library. Those options expose three values:

    Additionally, some CMake options were renamed to better express the impact on our users ( breaking change ). For example, now CMake options include:

    "},{"location":"blog/2024/06/14/mp-units-220-released/#configurable-contracts-checking","title":"Configurable contracts checking","text":"

    Before this release, the library always depended on gsl-lite to perform runtime contract and asserts checking. In this release we introduced new options to control if contract checking should be based on gsl-lite, ms-gsl, or may be completely disabled.

    "},{"location":"blog/2024/06/14/mp-units-220-released/#freestanding-support","title":"Freestanding support","text":"

    From this release it is possible to configure the library in the freestanding mode. This limits the functionality and interface of the library to be compatible with the freestanding implementations.

    Info

    To learn more, please refer to the Build options chapter.

    "},{"location":"blog/2024/06/14/mp-units-220-released/#simplified-quantity-point-support","title":"Simplified quantity point support","text":"

    This release significantly simplifies the usage of quantity points and affine space abstractions in general.

    Previously, the user always had to define an explicit point origin even if the domain being modeled does not have such an explicit origin. Now, in such cases, we can benefit from the implicit point origins. For example:

    NowBefore 
    quantity_point price_usd{100 * USD};\n
    constexpr struct zero final : absolute_point_origin<currency> {} zero;\n\nquantity_point price_usd = zero + 100 * USD;\n

    As we can see above, the new design allows direct-initializing quantity_point class template from a quantity, but only if the former one is defined in terms of the implicit point origin. Otherwise, an explicit origin still always has to be provided during initialization.

    Also, we introduced the possibility of specifying a default point origin in the unit definition. With that, we could provide proper temperature scales without forcing the user to always use the origins explicitly. Also, a new member function, .quantity_from_zero(), was introduced that always returns the quantity from the unit's specific point origin or from the implicit point origin otherwise.

    NowBefore 
    quantity_point temp{20 * deg_C};\nstd::cout << \"Temperature: \" << temp << \" (\"\n          << temp.in(deg_F).quantity_from_zero() << \", \"\n          << temp.in(K).quantity_from_zero() << \")\\n\";\n
    quantity_point temp = si::zeroth_degree_Celsius + 20 * deg_C;\nstd::cout << \"Temperature: \" << temp << \" (\"\n          << temp.in(deg_F).quantity_from(usc::zeroth_degree_Fahrenheit) << \", \"\n          << temp.in(K).quantity_from(si::zeroth_kelvin) << \")\\n\";\n

    More information about the new design can be found in The Affine Space chapter.

    "},{"location":"blog/2024/06/14/mp-units-220-released/#unified-temperature-point-origins-names","title":"Unified temperature point origins names","text":"

    By omission, we had the following temperature point origins in the library:

    With this release, the last one was renamed to usc::zeroth_degree_Fahrenheit to be consistently named with its corresponding unit and with the si::zeroth_degree_Celsius ( breaking change ).

    "},{"location":"blog/2024/06/14/mp-units-220-released/#changes-to-units-definitions","title":"Changes to units definitions","text":"

    There were several known issues when units were deriving from each other (e.g., #512 and #537). We could either highly complicate the framework to allow these which could result in much longer compilation times or disallow inheriting from units at all. We chose the second option.

    With this release all of of the units must be marked as final. To enforce this we have changed the definition of the Unit<T> concept, which now requires type T to be final ( breaking change ).

    WG21 Study Group 16 (Unicode) raised concerns about potential ABI issues when different translation units are compiled with different ordinary literal encodings. Those issues were resolved with a change to units definitions ( breaking change ). It affects only units that specify both Unicode and ASCII symbols. The new design requires the Unicode symbol to be provided as a UTF-8 literal.

    This also means that the basic_symbol_text has fixed character types for both symbols. This is why it was renamed to symbol_text ( breaking change ).

    NowBefore 
    inline constexpr struct ohm final : named_unit<symbol_text{u8\"\u03a9\", \"ohm\"}, volt / ampere> {} ohm;\n
    inline constexpr struct ohm : named_unit<basic_symbol_text{\"\u03a9\", \"ohm\"}, volt / ampere> {} ohm;\n

    Note

    On C++20-compliant compilers it should be enough to type the following in the unit's definition:

    inline constexpr struct ohm final : named_unit<{u8\"\u03a9\", \"ohm\"}, volt / ampere> {} ohm;\n
    "},{"location":"blog/2024/06/14/mp-units-220-released/#changes-to-dimension-quantity-specification-and-point-origins-definitions","title":"Changes to dimension, quantity specification, and point origins definitions","text":"

    Similarly to units, now also all dimensions, quantity specifications, and point origins have to be marked final ( breaking change ).

    NowBefore 
    inline constexpr struct dim_length final : base_dimension<\"L\"> {} dim_length;\ninline constexpr struct length final : quantity_spec<dim_length> {} length;\n\ninline constexpr struct absolute_zero final : absolute_point_origin<isq::thermodynamic_temperature> {} absolute_zero;\ninline constexpr auto zeroth_kelvin  = absolute_zero;\ninline constexpr struct kelvin final : named_unit<\"K\", kind_of<isq::thermodynamic_temperature>, zeroth_kelvin> {} kelvin;\n\ninline constexpr struct ice_point final : relative_point_origin<quantity_point{273'150 * milli<kelvin>}> {} ice_point;\ninline constexpr auto zeroth_degree_Celsius = ice_point;\ninline constexpr struct degree_Celsius final : named_unit<symbol_text{u8\"\u2103\", \"`C\"}, kelvin, zeroth_degree_Celsius> {} degree_Celsius;\n
    inline constexpr struct dim_length : base_dimension<\"L\"> {} dim_length;\ninline constexpr struct length : quantity_spec<dim_length> {} length;\n\ninline constexpr struct absolute_zero : absolute_point_origin<absolute_zero, isq::thermodynamic_temperature> {} absolute_zero;\ninline constexpr struct zeroth_kelvin : decltype(absolute_zero) {} zeroth_kelvin;\ninline constexpr struct kelvin : named_unit<\"K\", kind_of<isq::thermodynamic_temperature>, zeroth_kelvin> {} kelvin;\n\ninline constexpr struct ice_point : relative_point_origin<quantity_point{273'150 * milli<kelvin>}> {} ice_point;\ninline constexpr struct zeroth_degree_Celsius : decltype(ice_point) {} zeroth_degree_Celsius;\ninline constexpr struct degree_Celsius : named_unit<symbol_text{u8\"\u2103\", \"`C\"}, kelvin, zeroth_degree_Celsius> {} degree_Celsius;\n

    Please also note, that the absolute_point_origin does not use CRTP idiom anymore ( breaking change ).

    "},{"location":"blog/2024/06/14/mp-units-220-released/#improved-text-output","title":"Improved text output","text":"

    With this release, we can print not only whole quantities but also just their units or dimensions. Also, we fixed the std::format support so users can now enjoy full C++20 compatibility and don't have to use fmtlib anymore.

    We have also changed the grammar for quantities formatting ( breaking change ). It introduces the composition of underlying formatters that finally allows us to properly format user-defined representation types (assuming they have std::format support). Additionally, thanks to a new %? token, we can provide a custom format string that will properly print quantity of any unit.

    Here is a small preview of what is now available:

    using namespace mp_units::si::unit_symbols;\nusing namespace mp_units::international::unit_symbols;\nquantity q = (90. * km / h).in(mph);\n\nstd::cout << \"Number: \" << q.numerical_value_in(mph) << \"\\n\";\nstd::cout << \"Unit: \" << q.unit << \"\\n\";\nstd::cout << \"Dimension: \" << q.dimension << \"\\n\";\nstd::println(\"{::N[.2f]}\", q);\nstd::println(\"{:.4f} in {} of {}\", q.numerical_value_in(mph), q.unit, q.dimension);\nstd::println(\"{:%N in %U of %D:N[.4f]}\", q);\n
    Number: 55.9234\nUnit: mi/h\nDimension: LT\u207b\u00b9\n55.92 mi/h\n55.9234 in mi/h of LT\u207b\u00b9\n55.9234 in mi/h of LT\u207b\u00b9\n

    More on this subject can be found in the updated Text Output chapter.

    "},{"location":"blog/2024/06/14/mp-units-220-released/#improved-casts","title":"Improved casts","text":"

    We added a new conversion function. value_cast<Unit, Representation> forces the conversion of both a unit and representation type in one step and always ensures that the best precision is provided.

    Also, we have finally added proper implementations of value_cast and quantity_cast for quantity points.

    "},{"location":"blog/2024/06/14/mp-units-220-released/#even-better-error-messages","title":"Even better error messages","text":"

    This release made a few small refactorings that, without changing the user-facing API, allowed us to improve the readability of the generated types that can be observed in the compilation errors.

    Example 1 (clang):

    NowBefore 
    error: no matching function for call to 'time_to_goal'\n   26 |   const quantity ttg = time_to_goal(half_marathon_distance, pace);\n      |                        ^~~~~~~~~~~~\nnote: candidate template ignored: constraints not satisfied [with distance:auto = quantity<kilo_<metre>{}, double>,\n                                                                  speed:auto = quantity<derived_unit<second, per<kilo_<metre>>>{}, double>]\n   13 | QuantityOf<isq::time> auto time_to_goal(QuantityOf<isq::length> auto distance,\n      |                            ^\nnote: because 'QuantityOf<quantity<derived_unit<si::second, per<si::kilo_<si::metre> > >{{{}}}>, isq::speed>' evaluated to false\n   14 |                                         QuantityOf<isq::speed> auto speed)\n      |                                         ^\nnote: because 'QuantitySpecOf<std::remove_const_t<decltype(quantity<derived_unit<second, per<kilo_<metre> > >{{{}}}, double>::quantity_spec)>, struct speed{{{}}}>' evaluated to false\n   61 | concept QuantityOf = Quantity<Q> && QuantitySpecOf<std::remove_const_t<decltype(Q::quantity_spec)>, QS>;\n      |                                     ^\nnote: because 'implicitly_convertible(kind_of_<derived_quantity_spec<isq::time, per<isq::length> > >{}, struct speed{{{}}})' evaluated to false\n  147 |   QuantitySpec<T> && QuantitySpec<decltype(QS)> && implicitly_convertible(T{}, QS) &&\n      |                                                                         ^\n1 error generated.\nCompiler returned: 1\n
    error: no matching function for call to 'time_to_goal'\n   26 |   const quantity ttg = time_to_goal(half_marathon_distance, pace);\n      |                        ^~~~~~~~~~~~\nnote: candidate template ignored: constraints not satisfied [with distance:auto = quantity<kilo_<metre{{}}>{}, double>,\n                                                                  speed:auto = quantity<derived_unit<second, per<kilo_<metre{{}}>>>{}, double>]\n   13 | QuantityOf<isq::time> auto time_to_goal(QuantityOf<isq::length> auto distance,\n      |                            ^\nnote: because 'QuantityOf<quantity<derived_unit<si::second, per<si::kilo_<si::metre{{}}> > >{{{}}}>, isq::speed>' evaluated to false\n   14 |                                         QuantityOf<isq::speed> auto speed)\n      |                                         ^\nnote: because 'QuantitySpecOf<std::remove_const_t<decltype(quantity<derived_unit<second, per<kilo_<metre{{}}> > >{{{}}}, double>::quantity_spec)>, struct speed{{{}}}>' evaluated to false\n   61 | concept QuantityOf = Quantity<Q> && QuantitySpecOf<std::remove_const_t<decltype(Q::quantity_spec)>, QS>;\n      |                                     ^\nnote: because 'implicitly_convertible(kind_of_<derived_quantity_spec<isq::time, per<isq::length> >{{}, {{}}}>{}, struct speed{{{}}})' evaluated to false\n  147 |   QuantitySpec<T> && QuantitySpec<decltype(QS)> && implicitly_convertible(T{}, QS) &&\n      |                                                                         ^\n1 error generated.\nCompiler returned: 1\n

    Example 2 (gcc):

    NowBefore 
    error: no matching function for call to 'Box::Box(quantity<reference<isq::height, si::metre>(), int>, quantity<reference<horizontal_length, si::metre>(), int>,\n                                                  quantity<reference<isq::width, si::metre>(), int>)'\n   27 | Box my_box(isq::height(1 * m), horizontal_length(2 * m), isq::width(3 * m));\n      |                                                                           ^\nnote: candidate: 'Box::Box(quantity<reference<horizontal_length, si::metre>()>, quantity<reference<isq::width, si::metre>()>,\n                                          quantity<reference<isq::height, si::metre>()>)'\n   19 |   Box(quantity<horizontal_length[m]> l, quantity<isq::width[m]> w, quantity<isq::height[m]> h):\n      |   ^~~\nnote:   no known conversion for argument 1 from 'quantity<reference<isq::height, si::metre>(),int>'\n        to 'quantity<reference<horizontal_length, si::metre>(),double>'\n   19 |   Box(quantity<horizontal_length[m]> l, quantity<isq::width[m]> w, quantity<isq::height[m]> h):\n      |       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^\n
    error: no matching function for call to 'Box::Box(quantity<reference<isq::height(), si::metre()>(), int>, quantity<reference<horizontal_length(), si::metre()>(), int>,\n                                                  quantity<reference<isq::width(), si::metre()>(), int>)'\n   27 | Box my_box(isq::height(1 * m), horizontal_length(2 * m), isq::width(3 * m));\n      |                                                                           ^\nnote: candidate: 'Box::Box(quantity<reference<horizontal_length(), si::metre()>()>, quantity<reference<isq::width(), si::metre()>()>,\n                                          quantity<reference<isq::height(), si::metre()>()>)'\n   19 |   Box(quantity<horizontal_length[m]> l, quantity<isq::width[m]> w, quantity<isq::height[m]> h):\n      |   ^~~\nnote:   no known conversion for argument 1 from 'quantity<reference<isq::height(), si::metre()>(),int>'\n        to 'quantity<reference<horizontal_length(), si::metre()>(),double>'\n   19 |   Box(quantity<horizontal_length[m]> l, quantity<isq::width[m]> w, quantity<isq::height[m]> h):\n      |       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^\n
    "},{"location":"blog/2024/06/14/mp-units-220-released/#mathh-header-changes","title":"math.h header changes","text":"

    This release provided lots of changes to the mp_units/math.h header file.

    First, we got several outstanding contributions:

    Thanks!

    Additionally, we changed the namespace for trigonometric functions using SI units. Now they are inside of the mp_units::si subnamespace and not in mp_units::isq like it was the case before ( breaking change ).

    Also, the header itself was split into smaller pieces that improve C++20 modules definitions.

    "},{"location":"blog/2024/06/14/mp-units-220-released/#ratio-made-an-implementation-detail-of-the-library","title":"ratio made an implementation detail of the library","text":"

    We decided not to expose ratio and associated interfaces in the public part of the library ( breaking change ). Standardization of it could be problematic as we have std::ratio already.

    Alternatively, as in the public interface it was always only used with mag, we introduced a new helper called mag_ratio to provide the magnitude of the unit defined in terms of a rational conversion factor. Here is a comparison of the code with previous and current definitions:

    NowBefore 
    inline constexpr struct yard final : named_unit<\"yd\", mag_ratio<9'144, 10'000> * si::metre> {} yard;\ninline constexpr struct foot final : named_unit<\"ft\", mag_ratio<1, 3> * yard> {} foot;\n
    inline constexpr struct yard : named_unit<\"yd\", mag<ratio{9'144, 10'000}> * si::metre> {} yard;\ninline constexpr struct foot : named_unit<\"ft\", mag<ratio{1, 3}> * yard> {} foot;\n
    "},{"location":"blog/2024/09/27/mp-units-230-released/","title":"mp-units 2.3.0 released!","text":"

    A new product version can be obtained from GitHub and Conan.

    This release fine-tunes many key features of the library. This post describes the most interesting improvements, while a much longer list of the changes introduced by the new version can be found in our Release Notes.

    "},{"location":"blog/2024/09/27/mp-units-230-released/#cmake-and-conan-options-changed","title":"CMake and Conan options changed","text":"

    During the review on the ConanCenter, we got feedback that we should improve the handling of options for which value is automatically determined based on the current configuration. Instead of explicitly setting the auto value, we defer the choice between True/False until the configuration stage and set it there once all the settings are known. auto value for such option was removed ( breaking change ).

    If you didn't set any value at the command line for such options, everything stays the same for you. However, some changes are needed if you explicitly used auto like below:

    conan install . -o 'mp-units:std_format=auto' -s compiler.cppstd=23 -b missing\n

    Now you have to either skip such an option to keep automatic deduction:

    conan install . -s compiler.cppstd=23 -b missing\n

    or set it explicitly to True or False to force a specific configuration:

    conan install . -o 'mp-units:std_format=True' -s compiler.cppstd=23 -b missing\n
    "},{"location":"blog/2024/09/27/mp-units-230-released/#msvc-compiler-support","title":"MSVC compiler support","text":"

    The MSVC compiler has the most bugs in the C++20 support from all our compilers. However, with this release, we could apply many workarounds to the library's code to make it work. \ud83c\udf89

    Please note those workarounds were only applied to the library's code and not to our unit tests and examples. Trying to build the entire project on MSVC will inevitably fail to compile unless the MSVC bugs are resolved. MSVC developers still have some work to do.

    "},{"location":"blog/2024/09/27/mp-units-230-released/#representation-type-template-parameter-added-to-value-conversion-functions","title":"Representation type template parameter added to value conversion functions","text":"

    Previously, changing a representation type was only possible with a value_cast<NewRep>(q) non-member function while a change of unit was supported by all value_cast<NewU>(q), q.in(NewU), and q.force_in(NewU). The rationale for it was that passing an explicit type to a member function template requires a template disambiguator when we are dealing with a dependent name (e.g., quantity type is determined based on a template parameter).

    During a discussion in LEWGI at the St. Louis WG21 Meeting, we decided to provide such additional overloads despite possible issues when a dependent name is used. In such case, a user needs to provide a template disambiguator or switch back to using value_cast:

    // non-dependent name\nauto f(quantity<m, int> q)             { return q.in<double>(km); }\nauto g(quantity<m, int> q)             { return value_cast<double, km>(q); }\n\n// dependent name\nauto h(QuantityOf<isq::length> auto q) { return q.template in<double>(km); }\nauto i(QuantityOf<isq::length> auto q) { return value_cast<double, km>(q); }\n

    The table below provides all the value conversion functions in mp-units that may be run on x being the instance of either quantity or quantity_point:

    Forcing Representation Unit Member function Non-member function No Same u x.in(u) No T Same x.in<T>() No T u x.in<T>(u) Yes Same u x.force_in(u) value_cast<u>(x) Yes T Same x.force_in<T>() value_cast<T>(x) Yes T u x.force_in<T>(u) value_cast<u, T>(x) or value_cast<T, u>(x)"},{"location":"blog/2024/09/27/mp-units-230-released/#quantity-reference-specifiers","title":"Quantity reference specifiers","text":"

    The features described in this chapter directly solve an issue raised on std-proposals reflector. As it was reported, the code below may look correct, but it provides an invalid result:

    quantity Volume = 1.0 * m3;\nquantity Temperature = 28.0 * deg_C;\nquantity n_ = 0.04401 * kg / mol;\nquantity R_boltzman = 8.314 * N * m / (K * mol);\nquantity mass = 40.0 * kg;\nquantity Pressure = R_boltzman * Temperature.in(K) * mass / n_ / Volume;\nstd::cout << Pressure << \"\\n\";\n

    The problem is related to the accidental usage of a quantity rather than quantity_point for Temperature. This means that after conversion to kelvins, we will get 28 K instead of the expected 301.15 K, corrupting all further calculations.

    A correct code should use a quantity_point:

    quantity_point Temperature(28.0 * deg_C);\n

    This might be an obvious thing for domain experts, but new users of the library may not be aware of the affine space abstractions and how they influence temperature handling.

    After a lengthy discussion on handling such scenarios, we decided to:

    Here are the main points of this new design:

    1. All references/units that specify point origin in their definition (i.e., si::kelvin, \u00a0 \u00a0si::degree_Celsius, and usc::degree_Fahrenheit) are excluded from the multiply syntax ( breaking change ).

    2. A new delta quantity construction helper is introduced:

      • delta<m>(42) results with a quantity<si::metre, int>,
      • delta<deg_C>(5) results with a quantity<si::deg_C, int>.

    3. A new absolute quantity point construction helper is introduced:

      • absolute<m>(42) results with a quantity_point<si::metre, zeroth_point_origin<kind_of<isq::length>>{}, int>,
      • absolute<deg_C>(5) results with a quantity<si::metre, si::ice_point, int>.

    Info

    Please note that si::kelvin is also excluded from the multiply syntax to prevent the following surprising issues:

    NowBefore 
    quantity q = delta<K>(300);\nquantity_point qp = absolute<K>(300);\nstatic_assert(q.in(deg_C) != qp.in(deg_C).quantity_from_zero());\n
    quantity q(300 * K);\nquantity_point qp(300 * K);\nstatic_assert(q.in(deg_C) != qp.in(deg_C).quantity_from_zero());\n

    We believe that the code enforced with new utilities makes it much easier to understand what happens here.

    With such changes to the interface design, the offending code will not compile as initially written. Users will be forced to think more about what they write. To enable the compilation, the users have to create explicitly:

    Thanks to the new design, we can immediately see what happens here and why the result might be incorrect in the second case.

    "},{"location":"blog/2024/09/27/mp-units-230-released/#quantity_point_like_traits-are-based-on-numerical-value-instead-of-a-quantity","title":"quantity_point_like_traits are based on numerical value instead of a quantity","text":"

    In this release, we decided to fine-tune the traits that customize the conversion between custom quantity point types and the ones provided with mp-units ( breaking change ).

    Previously, such type traits were based on the quantity type. This was inconsistent with quantity_like_traits, that is working on raw values. Also, there are cases where a custom quantity point abstraction is not modelled with a quantity type. In such cases, the previous approach required additional types to be introduced for no good reason.

    NowBefore 
    template<>\nstruct mp_units::quantity_point_like_traits<Timestamp> {\n  static constexpr auto reference = si::second;\n  static constexpr auto point_origin = default_point_origin(reference);\n  using rep = decltype(Timestamp::seconds);\n\n  static constexpr convert_implicitly<rep> to_numerical_value(Timestamp ts)\n  {\n    return ts.seconds;\n  }\n\n  static constexpr convert_explicitly<Timestamp> from_numerical_value(rep v)\n  {\n    return Timestamp(v);\n  }\n};\n
    template<>\nstruct mp_units::quantity_point_like_traits<Timestamp> {\n  static constexpr auto reference = si::second;\n  static constexpr auto point_origin = default_point_origin(reference);\n  using rep = decltype(Timestamp::seconds);\n\n  static constexpr convert_implicitly<quantity<reference, rep>> to_quantity(Timestamp ts)\n  {\n    return ts.seconds * si::second;\n  }\n\n  static constexpr convert_explicitly<Timestamp> from_quantity(quantity<reference, rep> q)\n  {\n    return Timestamp(q.numerical_value_ref_in(si::second));\n  }\n};\n

    Note

    The old behavior is deprecated and will be removed in future releases.

    "},{"location":"blog/2024/09/27/mp-units-230-released/#magpi","title":"mag<pi>","text":"

    With this release, we introduced a new strongly-typed constant to create a magnitude involving scaling by pi. The solution used before was not consistent with magnitudes of integral values and also was leaking a floating-point value of std::numbers::pi_v<long double> to the resulting magnitude type. With the new approach, this is no longer the case, and the user-facing interface is more consistent:

    NowBefore 
    inline constexpr struct degree final : named_unit<{u8\"\u00b0\", \"deg\"}, mag<pi> / mag<180> * si::radian> {} degree;\n
    inline constexpr struct degree final : named_unit<{u8\"\u00b0\", \"deg\"}, mag_pi / mag<180> * si::radian> {} degree;\n

    Note

    The old mag_pi helper is marked as deprecated and will be removed in future releases.

    "},{"location":"blog/2024/09/27/mp-units-230-released/#common-units","title":"Common units","text":"

    Adding or subtracting two quantities of different units will force the library to find a common unit for those. This is to prevent data truncation. For the cases when one of the units is an integral multiple of the another, the resulting quantity will use a \"smaller\" one in its result. For example:

    static_assert((1 * kg + 1 * g).unit == g);\nstatic_assert((1 * km + 1 * mm).unit == mm);\nstatic_assert((1 * yd + 1 * mi).unit == yd);\n

    However, in many cases an arithmetic on quantities of different units will result in a yet another unit. This happens when none of the source units is an integral multiple of another. In such cases, the library returns a special type that denotes that we are dealing with a common unit of such an equation.

    Previously we returned a scaled unit calculated against our arbitrarily appointed reference unit. This resulted often in a long and messy type exposing the prime-factorized magnitude of the unit (implementation detail). In this release, we introduced a new common_unit wrapper for such cases:

    NowBefore 
    quantity q = 1 * km + 1 * mi;  // quantity<common_unit<international::mile, si::kilo_<si::metre>>{}, int>\n
    quantity q = 1 * km + 1 * mi;  // quantity<scaled_unit<magnitude<power_v<2, 3>{}, power_v<5, -3>{}>{}, si::metre>{}, int>\n

    Note

    A user should never explicitly instantiate a common_unit class template. The library's framework will do it based on the provided quantity equation.

    Such units need special printing rules for their symbols. As they represent a minimum set of common units resulting from the addition or subtraction of multiple quantities, from this release, we print all of them as a scaled version of the source unit. Previously we were printing them relative to some arbitrary reference unit (implementation detail) that often was not spelled by the user at all in the source code. For example the following:

    std::cout << 1 * km + 1 * mi << \"\\n\";\nstd::cout << 1 * nmi + 1 * mi << \"\\n\";\nstd::cout << 1 * km / h + 1 * m / s << \"\\n\";\n

    will print:

    NowBefore 
    40771 ([1/25146] mi = [1/15625] km)\n108167 ([1/50292] mi = [1/57875] nmi)\n23 ([1/5] km/h = [1/18] m/s)\n
    40771 [8/125] m\n108167 [4/125] m\n23 [1/18] m/s\n

    Thanks to the above, it might be easier for the user to reason about the magnitude of the resulting unit and its impact on the value stored in the quantity.

    Info

    In order to provide common_unit strong type unit wrapper we had to rename all the common_XXX() functions to get_common_XXX() ( breaking change ).

    "},{"location":"blog/2024/09/27/mp-units-230-released/#superpowers-of-the-unit-one","title":"Superpowers of the unit one","text":"

    In this release, we also added a long-awaited change. From now on a quantity of a unit one can be:

    NowBefore 
    quantity<one> inc(quantity<one> q) { return q + 1; }\nvoid legacy(double) { /* ... */ }\n\nif (auto q = inc(42); q != 0)\n  legacy(static_cast<int>(q));\n
    quantity<one> inc(quantity<one> q) { return q + 1 * one; }\nvoid legacy(double) { /* ... */ }\n\nif (auto q = inc(42 * one); q != 0 * one)\n  legacy(q.numerical_value_in(one));\n

    This property also expands to usual arithmetic operators.

    With the above change, we can now achieve the same results in a terser way:

    NowBefore 
    static_assert(10 * km / (5 * km) == 2);\nconst quantity gain = 1. / index;\n
    static_assert(10 * km / (5 * km) == 2 * one);\nconst quantity gain = 1. / index * one;\n

    Note

    Those rules do not apply to all the dimensionless quantities. It would be unsafe and misleading to allow such operations on units with a magnitude different than 1 (e.g., percent or radian).

    "},{"location":"blog/2024/09/27/mp-units-230-released/#import-std-support","title":"import std; support","text":"

    This release brings experimental support for import std;. The only compiler that supports it for now is clang-18+. Until all the compilers start to support it and CMake removes the experimental tag from this feature, we will also keep it experimental.

    As all of the C++ compilers are buggy for now, it is not allowed to bring the same definitions through the import std; and regular header files. This applies not only to the current project but also to all its dependencies. This is why, in order to use it with mp-units, we need to disable all the dependencies as well (enforced with conanfile.py). It means that we have to use std::format (instead of fmtlib) and remove functions contract checking.

    With the above assumptions, we can refactor our smoot example to:

    import mp_units;\nimport std;\n\nusing namespace mp_units;\n\ninline constexpr struct smoot final : named_unit<\"smoot\", mag<67> * usc::inch> {} smoot;\n\nint main()\n{\n  constexpr quantity dist = 364.4 * smoot;\n  std::println(\"Harvard Bridge length = {::N[.1f]} ({::N[.1f]}, {::N[.2f]}) \u00b1 1 \u03b5ar\",\n               dist, dist.in(usc::foot), dist.in(si::metre));\n}\n
    "},{"location":"blog/2024/09/27/mp-units-230-released/#unit_can_be_prefixed-removed","title":"unit_can_be_prefixed removed","text":"

    Previously, the unit_can_be_prefixed type trait was used to limit the possibility to prefix some units that are officially known as non-prefixable (e.g., hour, minute).

    It turned out that it is not easy to determine whether some units can be prefixed. For example, for degree Celsius, the ISO 80000-5 standard explicitly states:

    Prefixes are not allowed in combination with the unit \u00b0C.

    On the other hand this NIST page says:

    Prefix symbols may be used with the unit symbol \u00baC and prefix names may be used with the unit name \u201cdegree Celsius.\u201d For example, 12 m\u00baC (12 millidegrees Celsius) is acceptable.

    It seems that it is also a common engineering practice.

    To prevent such issues, we decided to simplify the library's design and remove the unit_can_be_prefixed type trait ( breaking change ).

    From now on, every named unit in the library can be prefixed with the SI or IEC prefix.

    "},{"location":"blog/2024/09/27/mp-units-230-released/#iec80000-system-renamed-to-iec","title":"iec80000 system renamed to iec","text":"

    As we mentioned IEC already, in this release, we decided to rename the name of the system and its corresponding namespace from iec80000 to iec ( breaking change ). This involves renaming of a defining header file and of the namespace it provides.

    With this change it should be easier to type the namespace name. This name is also more correct for some quantities and units that are introduced by IEC but not necessarily in the ISO/IEC 80000 series of documents (e.g., iec::var).

    Note

    The old iec80000 namespace in iec8000.h is marked as deprecated and will be removed in future releases.

    "},{"location":"blog/2024/09/27/mp-units-230-released/#error-messages-related-improvements","title":"Error messages-related improvements","text":"

    The readability of compile-time error messages is always a challenge for generic C++ libraries. However, for quantities and units library, generating readable errors is the most important requirement. If you do not make errors, you do not need such a library in your project .

    This is why we put lots of effort into improving here. Besides submitting compiler bugs to improve on their part, we also try to do our best here.

    Some compilers do not present the type resulting from calling a function within a template argument. This ends up with statements like get_quantity_spec(si::second{}) in the error message. Some less experienced users of the library may not know what this mean, and then why the conversion error happens.

    To improve this, we injected additional helper concepts into the definitions. It results with a bit longer but a more readable error in the end.

    For example:

    NowBefore 
    error: no matching member function for call to 'in'\n   15 | const quantity time_to_goal = (distance * speed).in(s);\n      |                               ~~~~~~~~~~~~~~~~~~~^~\nnote: candidate template ignored: constraints not satisfied [with ToU = struct second]\n  221 |   [[nodiscard]] constexpr QuantityOf<quantity_spec> auto in(ToU) const\n      |                                                          ^\nnote: because 'detail::UnitCompatibleWith<si::second, unit, quantity_spec>' evaluated to false\n  219 |   template<detail::UnitCompatibleWith<unit, quantity_spec> ToU>\n      |            ^\nnote: because '!AssociatedUnit<si::second>' evaluated to false\n  164 |   (!AssociatedUnit<U> || UnitOf<U, QS>) && detail::UnitConvertibleTo<FromU, U{}>;\n      |    ^\nnote: and 'UnitOf<si::second, kind_of_<derived_quantity_spec<power<isq::length, 2>, per<isq::time> > >{}>' evaluated to false\n  164 |   (!AssociatedUnit<U> || UnitOf<U, QS>) && detail::UnitConvertibleTo<FromU, U{}>;\n      |                          ^\nnote: because 'detail::QuantitySpecConvertibleTo<get_quantity_spec(si::second{}), kind_of_<derived_quantity_spec<power<isq::length, 2>, per<isq::time> > >{}>' evaluated to false\n  141 |                  detail::QuantitySpecConvertibleTo<get_quantity_spec(U{}), QS> &&\n      |                  ^\nnote: because 'implicitly_convertible(kind_of_<struct time>{}, kind_of_<derived_quantity_spec<power<isq::length, 2>, per<isq::time> > >{})' evaluated to false\n  151 |   implicitly_convertible(From, To);\n      |   ^\n1 error generated.\nCompiler returned: 1\n
    error: no matching member function for call to 'in'\n   15 | const quantity time_to_goal = (distance * speed).in(s);\n      |                               ~~~~~~~~~~~~~~~~~~~^~\nnote: candidate template ignored: constraints not satisfied [with U = struct second]\n  185 |   [[nodiscard]] constexpr QuantityOf<quantity_spec> auto in(U) const\n      |                                                          ^\nnote: because 'detail::UnitCompatibleWith<si::second, unit, quantity_spec>' evaluated to false\n  183 |   template<detail::UnitCompatibleWith<unit, quantity_spec> U>\n      |            ^\nnote: because '!AssociatedUnit<si::second>' evaluated to false\n  207 |   (!AssociatedUnit<U> || UnitOf<U, QS>)&&(detail::have_same_canonical_reference_unit(U{}, U2));\n      |    ^\nnote: and 'UnitOf<si::second, kind_of_<derived_quantity_spec<power<isq::length, 2>, per<isq::time> > >{}>' evaluated to false\n  207 |   (!AssociatedUnit<U> || UnitOf<U, QS>)&&(detail::have_same_canonical_reference_unit(U{}, U2));\n      |                          ^\nnote: because 'implicitly_convertible(get_quantity_spec(si::second{}), kind_of_<derived_quantity_spec<power<length, 2>, per<time> > >{})' evaluated to false\n  187 |   implicitly_convertible(get_quantity_spec(U{}), QS) &&\n      |   ^\n1 error generated.\nCompiler returned: 1\n

    Note

    The above error messages were stripped a bit of the additional information (file name, namespace name, nested curlies) to provide better readability.

    "},{"location":"blog/2024/11/05/mp-units-240-released/","title":"mp-units 2.4.0 released!","text":"

    A new product version can be obtained from GitHub and Conan.

    This release was unexpected. We planned a significant new feature to happen next, but while preparing for it, and also while writing API Reference documentation, we made so many vital fixes and improvements that we decided that they deserve a dedicated release first.

    This post describes the most significant improvements while a much longer list of the changes introduced by the new version can be found in our Release Notes.

    "},{"location":"blog/2024/11/05/mp-units-240-released/#isq-quantities-cleanup","title":"ISQ quantities cleanup","text":"

    Initially, we kept quantities defined in \"IEC 80000-13: Information science and technology\" in a standalone iec80000 namespace, which was renamed to iec in the previous release. It turned out that this was incorrect. Those quantities are also a part of the ISQ. This is why, in this release, we moved all of them to the isq namespace ( breaking change ).

    From now on, iec namespace does not provide any quantities and serves purely as a system of units definition. It contains binary prefixes (based on the powers of two) and some units introduced by IEC (e.g., var, erlang, bit, or `baud).

    Note

    The quantities in iec namespace are now deprecated and will be removed in future releases.

    Also, it turns out that the latest ISO 80000-3 revision makes a small cleanup to the phase_speed and group_speed quantities. Those were always defined as scalar quantities but also had alternative names phase_velocity and group_velocity. This is misleading as velocity is typically considered a vector quantity. It is why those XXX_velocity aliases were removed from the ISO standard and from mp-units library ( breaking change ).

    "},{"location":"blog/2024/11/05/mp-units-240-released/#units-equality","title":"Units equality","text":"

    Previously we assumed that units like J, N m, and kg m\u00b2/s\u00b2 are equal. In some cases, this might not be entirely correct. Some quantities require a specific derived unit instead of a unit with a special name. For example:

    This is why, starting from this release units like J, N m, and kg m\u00b2/s\u00b2 will not compare equal ( breaking change ). However, they are deemed equivalent:

    static_assert(equivalent(J, N * m));\nstatic_assert(equivalent(W, V * A));\n
    "},{"location":"blog/2024/11/05/mp-units-240-released/#portable-text-output","title":"Portable text output","text":"

    From the very beginning, the text output of symbols could be formatted in two different ways:

    mp-units used the terms \"Unicode\" or \"ASCII\" and 'U' or 'A' formatting options for them. Even though those terms are widely understood in the C++ community, they are technically incorrect.

    During the recent SG16 meeting, we looked for proper alternatives and ended up with the \"portable\" and \"UTF-8\" terms ( breaking change ).

    From now on, we will provide the following:

    Note

    The old identifiers and formatting options are now deprecated and will be removed in future releases.

    "},{"location":"blog/2024/11/05/mp-units-240-released/#char_traits-removed-from-fixed_string","title":"char_traits removed from fixed_string","text":"

    During the same SG16 meeting, the room was strongly against providing char_traits for fixed_string. This is why char_traits support was removed in this release ( breaking change ).

    "},{"location":"blog/2024/11/05/mp-units-240-released/#improved-units-text-output","title":"Improved units' text output","text":"

    In the previous release, we introduced common unit abstraction. Initially, all its components were printed in parenthesis which contained a list of all the scaled units separated with =. After some feedback, we decided to change it to a new syntax.

    For example, the following:

    std::cout << 1 * km + 1 * mi << \"\\n\";\nstd::cout << 1 * nmi + 1 * mi << \"\\n\";\nstd::cout << 1 * km / h + 1 * m / s << \"\\n\";\n

    will print:

    NowBefore 
    40771 EQUIV{[1/25146 mi], [1/15625 km]}\n108167 EQUIV{[1/50292 mi], [1/57875 nmi]}\n23 EQUIV{[1/5 km/h], [1/18 m/s]}\n
    40771 ([1/25146] mi = [1/15625] km)\n108167 ([1/50292] mi = [1/57875] nmi)\n23 ([1/5] km/h = [1/18] m/s)\n

    As we can see above, the scaled units output changed as well. Now, the entire scaled unit is encapsulated within [...] brackets to better denote its scope.

    Additionally, small magnitudes of scaled units do not use the power of 10, and also scaled units do not have a composition priority over the derived units anymore.

    As a result of those changes, the following:

    constexpr Unit auto L_per_100km = L / (mag<100> * km);\nstd::cout << 6.7 * L_per_100km << \"\\n\";\n

    prints:

    NowBefore 
    6.7 L/[100 km]\n
    6.7 \u00d7 10\u207b\u00b2 l/km\n

    One more change that we can see above is that litre now use 'L' instead of 'l' for its symbol. The latter one too often is confused with the number 1.

    The next improvement adds proper formatting support for magnitudes. All of the formatting options that were working before for the unit symbols now also work for magnitudes.

    For example:

    using enum text_encoding;\nusing enum unit_symbol_solidus;\nusing usf = unit_symbol_formatting;\n\nstatic_assert(unit_symbol(mag<1> / (mag<2> * mag<pi>)*metre) == \"[2\u207b\u00b9 \ud835\udf0b\u207b\u00b9 m]\");\nstatic_assert(unit_symbol<usf{.solidus = always}>(mag<1> / (mag<2> * mag<pi>)*metre) == \"[1/(2 \ud835\udf0b) m]\");\nstatic_assert(unit_symbol<usf{.encoding = portable, .solidus = always}>(mag<1> / (mag<2> * mag<pi>)*metre) ==\n              \"[1/(2 pi) m]\");\n

    As we can see above, the library also learned how to print magnitude symbols. This required a change in the mag_constant definition. Now, it takes a magnitude symbol and has to be final like for other similar types in the library ( breaking change ):

    inline constexpr struct pi final : mag_constant<symbol_text{u8\"\u03c0\", \"pi\"}, std::numbers::pi_v<long double>> {} pi;\ninline constexpr auto \u03c0 = pi;\n
    "},{"location":"blog/2024/11/05/mp-units-240-released/#unicode-identifiers","title":"Unicode identifiers","text":"

    The example above introduced something interesting: a \u03c0 identifier for a variable. With the latest changes to the C++ language, we can officially use Unicode symbols as identifiers in the C++ code.

    In this release, we've added Unicode identifiers support not only for \u03c0 magnitude constant but also for unit symbols.

    Now we can type the following:

    With UTF-8 glyphsPortable 
    quantity resistance = 60 * k\u03a9;\nquantity capacitance = 100 * \u00b5F;\n
    quantity resistance = 60 * kohm;\nquantity capacitance = 100 * uF;\n

    This might make the source code easier to understand, but typing those identifiers can be tricky. Sometimes, the best solution to type it might be a copy-paste approach. If we do not like this idea, we can still use old portable identifiers for those as well.

    "},{"location":"blog/2024/11/05/mp-units-240-released/#convertibility-with-quantitylike-and-quantitypointlike-entities","title":"Convertibility with QuantityLike and QuantityPointLike entities","text":"

    In this release, we decided to fine-tune further the traits that customize the conversion between custom quantity and quantity point types and the ones provided with mp-units ( breaking change ).

    Previously, to_numerical_value and from_numerical_value returned a type wrapped in a special tag type describing the conversion type (explicit or implicit).

    This was a novel and experimental approach. Finally, we decided not to do it and used a bit more verbose but a more standard solution. From now on, we need to provide two additional static data members of type bool:

    NowBefore 
    template<>\nstruct mp_units::quantity_point_like_traits<Timestamp> {\n  static constexpr auto reference = si::second;\n  static constexpr auto point_origin = default_point_origin(reference);\n  static constexpr bool explicit_import = false;\n  static constexpr bool explicit_export = true;\n  using rep = decltype(Timestamp::seconds);\n\n  static constexpr rep to_numerical_value(Timestamp ts)\n  {\n    return ts.seconds;\n  }\n\n  static constexpr Timestamp from_numerical_value(rep v)\n  {\n    return Timestamp(v);\n  }\n};\n
    template<>\nstruct mp_units::quantity_point_like_traits<Timestamp> {\n  static constexpr auto reference = si::second;\n  static constexpr auto point_origin = default_point_origin(reference);\n  using rep = decltype(Timestamp::seconds);\n\n  static constexpr convert_implicitly<rep> to_numerical_value(Timestamp ts)\n  {\n    return ts.seconds;\n  }\n\n  static constexpr convert_explicitly<Timestamp> from_numerical_value(rep v)\n  {\n    return Timestamp(v);\n  }\n};\n
    "},{"location":"blog/2024/11/05/mp-units-240-released/#symbolic-constants-implementation-should-be-implementation-defined","title":"Symbolic constants implementation should be implementation-defined","text":"

    In the process of writing API Reference, we decided to hide all the metadata associated with symbolic constants - tag types used to define units, dimensions, quantity specification, etc. ( breaking change ).

    All the types and values exposed by such types are needed only in the implementation details of the library. Users should not need them. Hiding those and making them implementation-defined gives other vendors the freedom to choose different ways to implement features of this library in their codebases.

    Important

    Based on Hyrum's Law some users may depend on this information already, and this release will break their code.

    If that is the case for you, we would love to hear about your use case and its rationale. It may mean that we should either:

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/","title":"Bringing Quantity-Safety To The Next Level","text":"

    All quantities and units libraries need to be unit-safe. Most of the libraries on the market do this correctly. Some of them are also dimension-safe, which adds another level of protection for their users.

    mp-units is probably the only library on the market that additionally is quantity-safe. This gives a new quality and possibilities. I've described the major idea behind it, implementation details, and benefits to the users in the series of posts about the International System of Quantities.

    However, this is only the beginning. We've always planned more and worked on the extensions in our free time. In this post, I will describe:

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#quantity-characters","title":"Quantity characters","text":"

    A quantity character determines the properties and operations that can be performed on the numerical value of a quantity.

    Quantities defined by the ISQ may be of the following characters:

    From the beginning, mp-units V2 was meant to properly support quantities of various characters. By default, all quantity types are scalars, but we can set any other quantity character in a quantity_spec definition. For example:

    inline constexpr struct displacement final : quantity_spec<length, quantity_character::vector> {} displacement;\n

    Character of derived quantities is inherited from the quantity equation taking into account the operations and their ingredients. For example the below velocity quantity will automatically get a vector character without the need to explicitly state it in the definition:

    inline constexpr struct velocity final : quantity_spec<displacement / duration> {} velocity;\n

    Similarly, the below will yield a speed quantity of a scalar character:

    inline constexpr struct speed final : quantity_spec<magnitude(velocity)> {} speed;\n
    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#representation-types","title":"Representation types","text":"

    mp-units V2 requires providing representation types compatible with a specific character set in its quantity_spec definition:

    template<Reference auto R, RepresentationOf<get_quantity_spec(R)> Rep = double>\nclass quantity;\n

    For example, this allows us to check that vector representation type is used to construct a velocity quantity and to ensure that speed gets a scalar:

    quantity q = vector{1, 2, 3} * m / s;\nquantity velocity = isq::velocity(q);\n// quantity speed = isq::speed(q);     // Compile-time error\n

    Another example here may be a complex power quantity that should use a representation type modeling a complex number, but apparent power, active power, and reactive power should get scalars.

    As we can see above, in the case of q, we can use any representation type with a quantity kind that just specify a unit (simple quantities). However, we need to provide a compatible representation type when we want to use strongly-typed quantities and be quantity-safe.

    Such checks already prevent many simple but common errors of mixing similar quantities in a specific domain.

    Info

    It is a common engineering practice to use fundamental types for vector quantities when we know the direction of the vector. For example, in many cases, we use double to express velocity or acceleration. In such cases, negative values mean moving backward or decelerating. This is why we also decided to allow such use cases in the library. A scalar representation type that provides abs() member or non-member function or works with std::abs() is considered a one-dimensional vector type:

    quantity speed = isq::speed(60 * km / h);\nquantity velocity = isq::velocity(60 * km / h);\n
    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#character-specific-operations","title":"Character-specific operations","text":"

    Checking the representation type is only the first step in bringing additional safety. The real power comes with implementing character-specific operations.

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#current-state-of-the-art","title":"Current state of the art","text":"

    Most units libraries on the market (not only for C++) provide only regular arithmetic operations for scalars and don't constrain them for quantities of other characters. They also do not offer any character-specific operations.

    For example, let's look closer into vector quantities. Most of the libraries on the market will happily accept the following or similar code:

    auto force = get_force();\nauto length = get_length();\nauto work = force * length;\n

    They will also accept the following line:

    auto moment_of_force = force * length;\n

    Does it mean that moment of force and work are the same quantities? Of course not! It is just how naive most libraries are today.

    But first, to defend them, I must admit that the behavior above is partially OK. force * length could yield some specific quantity, but it is definitely not work or moment of force.

    There are two problems here:

    1. Libraries on the market are not aware of the characters of the quantities being used in the equation. This means they can't prevent scalar arithmetic operations from being performed on vector quantities. This typically leads to compile-time errors when a proper linear algebra representation type is used in a quantity, as most linear algebra libraries will not overload operator* for vectors, and those that do, treat it as a dot product, which returns a scalar.
    2. None of the libraries allows us to constrain the return type of such multiplication with a specific quantity type to specify exactly what we want to achieve. Most of them allow for replacing auto with a type that describes just a unit, or, at best, the dimension. This means that all of them are unit-safe, and some are also dimension-safe. However, this is not helpful here and does not allow the library to do any additional compile-time checks on the resulting quantities. The fact that we named the results as work or moment_of_force does not mean anything to the compiler or the library being used.

    This isn't good.

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#benefits-of-quantity-safe-library","title":"Benefits of quantity-safe library","text":"

    As we've stated in the beginning, mp-units, besides being unit-safe and dimension-safe, is also quantity-safe. Let's see what it means.

    Note

    The features described below are planned for the next major release of the library and are not available on the master branch as of today.

    First, we repeat what other libraries did:

    quantity force = get_force();\nquantity length = get_length();\nquantity q1 = force * length;\n

    The code compiles as long as length is a scalar quantity with a scalar representation type. We can always multiply or divide a vector quantity (e.g., force) by a scalar one.

    However, things stop compiling when we want to convert the obtained result to a specific quantity type:

    // quantity moment_of_force = isq::moment_of_force(q1);  // Compile-time error\n// quantity work = isq::work(q1);                        // Compile-time error\n

    Neither moment of force nor work quantity can be created from a scalar length. We need very specific vector quantities of kind length to do that:

    quantity displacement = get_displacement();\nquantity position_vector = get_position_vector();\n

    Now, if we try to multiply the variables as before, we will end up with a compilation error:

    // quantity q2 = force * displacement;                   // Compile-time error\n// quantity q3 = force * position_vector;                // Compile-time error\n

    Multiplication on vectors is mathematically not defined. We have to use proper operations:

    quantity q2 = scalar_product(force, displacement);\nquantity q3 = scalar_product(force, position_vector);\nquantity q4 = vector_product(force, displacement);\nquantity q5 = vector_product(force, position_vector);\n

    All of the above compile and result in some quantities. After that, we can try to convert those results to our required quantities:

    quantity work = isq::work(q2).in[J];\n// quantity work = isq::work(q3);                        // Compile-time error\n// quantity work = isq::work(q4);                        // Compile-time error\n// quantity work = isq::work(q5);                        // Compile-time error\n

    Important

    It is essential to realize that just like multiplication and division are for scalars, vector and scalar products are for vectors. We never want to accept a quantity that accidentally was created with multiplication instead of division of its arguments or with the scalar product instead of a vector product, right?

    So we are done with work. Let's create a moment of force quantity as well. It might be surprising to many that none of the following code compiles:

    // quantity moment_of_force = isq::moment_of_force(q2);  // Compile-time error\n// quantity moment_of_force = isq::moment_of_force(q3);  // Compile-time error\n// quantity moment_of_force = isq::moment_of_force(q4);  // Compile-time error\n// quantity moment_of_force = isq::moment_of_force(q5);  // Compile-time error\n

    Do you know why it does not compile? Please try to think about it for a minute and figure out what is the problem before checking the answer below.

    !!! Spoiler alert !!!

    Vector product is anti-commutative. Similarly to the division for scalars, for a vector product it is important to decide which quantity we put on the left and right-hand side of the operation.

    To make it compile, we need to reverse the arguments of a vector_product() operation:

    quantity q6 = vector_product(position_vector, force);\nquantity moment_of_force = isq::moment_of_force(q6);\n

    Do you start to see the need for such checks at compile-time already?

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#explicit-conversions-are-not-really-needed","title":"Explicit conversions are not really needed","text":"

    You may be worried by the fact that we needed explicit quantity conversions above and that the code without them compiled fine. It might look like a safety pitfall, but it is really not an issue.

    The code above used a quantity CTAD placeholder which works a bit like auto. It accepts any quantity and deduced proper type for it. And all of the above operations resulted in some quantities, but often not the ones we were interested in.

    In the production code, we deal with strong types in many places (members in classes, function arguments and return types, etc.). In generic code, we should use concepts to constrain template parameters. This will be enough to guarantee quantity-safety.

    For example:

    void func1(quantity<isq::work[J]> w);\nvoid func2(QuantityOf<isq::moment_of_force> auto mof);\n\nfunc1(q2);\nfunc2(q6);\n// func1(q6);  // Compile-time error\n// func2(q2);  // Compile-time error\n
    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#peeking-under-the-hood","title":"Peeking under the hood","text":"

    Let's look at the definitions of work and moment of force quantities to understand how and why the above works:

    inline constexpr struct work final : quantity_spec<scalar_product(force, displacement)> {} work;\ninline constexpr struct moment_of_force final : quantity_spec<vector_product(position_vector, force)> {} moment_of_force;\n

    scalar_product() and vector_product() functions are overloaded not only for quantity but also for quantity_spec types. The results of such operations are symbolic expressions that identify those operations. When used as a quantity recipe in a quantity_spec definition, they tell the library which derived quantities may be implicitly converted to our quantity.

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#what-do-other-libraries-do","title":"What do other libraries do?","text":"

    I am probably not wrong in stating that none of the major C++ units libraries on the market provides vector or complex operations on quantities. This is why none of them will work when a proper representation type will be provided to a quantity. Trying to do any operations on a quantity with a linear algebra vector as its representation type will fail to compile.

    This is also mostly true for other programming languages. A great exception, and in fact the only library that I know which provides such operations, is Python's Pint (thanks to NumPy support).

    As other libraries do not support quantities of a vector type, they require users to create homogenous vectors of quantities and do all of the linear algebra operations with a 3rd party library. This approach can't be quantity-safe!

    In such scenarios, the units library can't detect if an external linear algebra library performs a scalar or vector product operation. It only observes the individual multiplications on scalar ingredients of an external vector type. This is actually why such multiplication operations are provided in other units libraries in the first place.

    Let's compare those approaches:

    Quantity-SafeAlso Quantity-SafeOther units libraries 
    quantity displacement_1 = isq::displacement(la::vector{1, 2, 3} * m);\nquantity displacement_2 = isq::displacement(la::vector{2, 1, 0} * m);\nquantity displacement = displacement_1 + displacement_2;\nquantity force = isq::force(la::vector{42, 42, 42} * N);\nquantity work = isq::work(scalar_product(force, displacement));\n
    quantity displacement_1 = la::vector{1, 2, 3} * m;\nquantity displacement_2 = la::vector{2, 1, 0} * m;\nquantity displacement = displacement_1 + displacement_2;\nquantity force = la::vector{42, 42, 42} * N;\nquantity<isq::work[J]> work = scalar_product(force, displacement);\n
    la::vector<quantity<si::metre>> displacement_1 = la::vector{1 * m, 2 * m, 3 * m};\nla::vector<quantity<si::metre>> displacement_2 = la::vector{2 * m, 1 * m, 0 * m};\nla::vector<quantity<si::metre>> displacement = displacement_1 + displacement_2;\nla::vector<quantity<si::newton>> force = la::vector{42 * N, 42 * N, 42 * N};\nquantity<si::joule> work = la::scalar_product(force, displacement);\n

    Of course, someone could argue that incorrect use of a vector product operation above would also be safe as it will not compile as the return type differs. Yes, it is true. However, please remember that there are more cases where errors may happen.

    For example, an external linear algebra library will not protect us from providing arguments to a vector product in an invalid order.

    Also, our work quantity will never be able to detect if what we are trying to assign to it is a result of a scalar product of two vector quantities of displacement and force, or maybe just some naive multiplication of scalar quantities that accidentally matched the dimensionality of the expected result.

    Please also remember that the quantity characters are not only about linear algebra. For example, in the case of complex quantities, we want to ensure that only:

    Mixing the above is a fatal error in power systems engineering.

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#implementation-challenges","title":"Implementation challenges","text":"

    I had planned to implement the above features for a few years now but never had enough time to do it. Now, I am close to finishing the work. However, I've discovered a few interesting issues on the way, and I have to solve them before putting my code on the mainline and releasing the next mp-units version.

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#modeling-magnitudes","title":"Modeling magnitudes","text":"

    Let's dig in a bit more into proper modelling of position vector and displacement quantities. First, we have to think to which scalar quantities their magnitude should convert to:

    Taking the above into account, we should refactor our tree of quantities of kind length into the following:

    flowchart TD\n    length[\"<b>length</b><br>[m]\"]\n    length --- width[\"<b>width</b> / <b>breadth</b>\"]\n    length --- height[\"<b>height</b> / <b>depth</b> / <b>altitude</b>\"]\n    width --- thickness[\"<b>thickness</b>\"]\n    width --- diameter[\"<b>diameter</b>\"]\n    width --- radius[\"<b>radius</b>\"]\n    radius --- radius_of_curvature[\"<b>radius_of_curvature</b>\"]\n    length --- path_length[\"<b>path_length</b>\"]\n    path_length --- distance[\"<b>distance</b>\"]\n    distance --- displacement[\"<b>displacement</b><br>{vector}\"]\n    distance --- radial_distance[\"<b>radial_distance</b>\"]\n    radial_distance --- position_vector[\"<b>position_vector</b><br>{vector}\"]\n    length --- wavelength[\"<b>wavelength</b>\"]

    Having the above, we can look a bit closer into how velocity and speed are defined in the ISQ:

    ISO 80000-3: Space and time

    velocity - vector quantity giving the rate of change of a position vector.

    speed - magnitude of the velocity.

    Change of a position vector is nothing else than a displacement. This means that velocity and speed can be defined as follows:

    inline constexpr struct velocity final : quantity_spec<displacement / duration> {} velocity;\ninline constexpr struct speed final : quantity_spec<magnitude(velocity)> {} speed;\n

    This is compatible with the ISQ definitions. However, we should check what it means from the engineering point of view. Let's assume that we want to calculate speed directly from a distance traveled and duration, without using any vector quantities like displacement or velocity:

    quantity<isq::distance[m]> distance = 42 * m;\nquantity<isq::duration[s]> duration = 2 * s;\n// quantity<isq::speed[m / s]> speed = distance / duration;  // Compile-time error\n

    The above does not compile because distance quantity is not implicitly convertible to magnitude(displacement). This is the same case as stating that not every length is a distance. We need to cast here explicitly. To fix it, we can do any of the below:

    quantity<isq::speed[m / s]> speed1 = isq::speed(distance / duration);\nquantity<isq::speed[m / s]> speed2 = magnitude(isq::displacement)(distance) / duration;\n

    Also, the following will work:

    quantity length_kind = 42 * m;\nquantity<isq::speed[m / s]> speed3 = length_kind / duration;\n

    If we do not specify a specific quantity type and just use an SI unit, then we deal with the kind of quantity. Such quantity can behave like any quantity from the hierarchy tree with the same character, so it is also the same as magnitude(isq::displacement).

    Question

    Is it good enough from the engineering and usability point of views? If you would like to share your thoughts, please provide your comments below the article.

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#more-about-displacement-and-position-vector","title":"More about displacement and position vector","text":"

    As we've stated above, a change of position vector is a displacement. Let's try to calculate it here:

    quantity pos1 = isq::position_vector(vector{1, 2} * m);\nquantity pos2 = isq::position_vector(vector{2, 3} * m);\nquantity q7 = pos2 - pos1;\n// quantity<isq::displacement[m], vector> displacement = q7;  // Compile-time error\n// quantity displacement = isq::displacement(q7);             // Compile-time error\nquantity displacement = quantity_cast<isq::displacement>(q7);\n

    Again, the above might be surprising and considered a usability issue. Let me describe why the code behaves like that.

    As of today, the result of an addition or subtraction of two quantities is their common quantity type. When subtracting two position vectors we end up with a position vector. Looking at the above hierarchy tree, we can easily see that position vector and displacement are on different branches. This prevents implicit and explicit conversions between those. The only one allowed to force such a conversion is an explicit cast.

    If we think more about it, this makes a lot of sense. Position vector is not a special case of displacement or vice versa. Those should not be convertible. We do not want the code to compile when we accidentally pass a position vector to the numerator of the equation for velocity, right? What does calculating the velocity for a position vector mean?

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#affine-spaces-within-quantity-trees","title":"Affine spaces within quantity trees","text":"

    Also, let's look at the type of variable q7. We know that subtracting two quantities of the same type results in a quantity of the same type. This is also the case when we do it for position vectors. We will see the same resulting type when we add two position vectors as well. But wait... What does it actually mean to add two position vectors?

    Looks familiar? Yes, we can clearly see that we are dealing with yet another case of the affine space. This time, it is hidden within the quantities hierarchy tree. This also means that adding a position vector and a displacement should result in a position vector. Let's try to do it:

    quantity q8 = pos1 + displacement;                       // Often a compile-time error\n

    Unfortunately, this often fails on the very first step, even before assigning the result to the position vector quantity. The reason for this is that in the hierarchy tree, the first common node for position vector and displacement is distance, which is a scalar quantity. Trying to use a vector representation type for a scalar quantity yields an error as a result of already existing checks described in the Representation types chapter.

    However, the code will compile if we use the same representation type for scalar and vector quantity (e.g., int or double may be used as a vector representation type for a well-known axis). In this case, we will end up with:

    // quantity<isq::position_vector[m], vector> pos3 = q8;       // Compile-time error\nquantity<isq::position_vector[m], vector> pos3 = isq::position_vector(q8);\n

    We need to convert a distance explicitly to a position vector quantity to move \"down\" over a branch in a hierarchy tree.

    It is important to note that there are more quantities that may behave the same. For example, altitude/height and time/duration may also form similar affine spaces. More similar examples can be found in other hierarchy trees.

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#extending-arithmetic-on-quantity-specifications","title":"Extending arithmetic on quantity specifications","text":"

    mp-units provided support for multiplication and division of quantity_spec from the beginning. It was needed to obtain derived quantities. Adding support for quantity characters also added special operations (e.g., magnitude(), scalar_product(), etc.) on quantity_spec arguments. If we want to support such affine space abstractions, we must also add support for addition and subtraction, which may yield different results.

    For example:

    static_assert(isq::length + isq::length == isq::length);\nstatic_assert(isq::height + isq::width == isq::length);\nstatic_assert(isq::altitude + isq::height == isq::altitude);\nstatic_assert(isq::height + isq::altitude == isq::altitude);\n\nstatic_assert(isq::length - isq::length == isq::length);\nstatic_assert(isq::height - isq::width == isq::length);\nstatic_assert(isq::altitude - isq::height == isq::altitude);\nstatic_assert(isq::altitude - isq::altitude == isq::height);\n

    Also, some operations should not compile. For example:

    // auto qs1 = isq::altitude + isq::altitude;  // Compile-time error\n// auto qs2 = isq::height - isq::altitude;    // Compile-time error\n
    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#defining-affine-space-abstractions-in-a-quantity_spec","title":"Defining affine space abstractions in a quantity_spec","text":"

    We can add support for the above by adding point_for<QuantitySpec> attribute to the quantity_spec definition:

    inline constexpr struct height final : quantity_spec<length> {} height;\ninline constexpr struct altitude final : quantity_spec<length, point_for<height>> {} altitude;\ninline constexpr struct displacement final : quantity_spec<distance, quantity_character::vector> {} displacement;\ninline constexpr struct position_vector final : quantity_spec<radial_distance, point_for<displacement>, quantity_character::vector> {} position_vector;\n

    Thanks to the above, the library always knows a \"delta\" quantity for a \"point\" type. I've implemented this logic, got great results, and thought I was done. But next, I realized that I need to update a few more things.

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#adding-support-to-quantity_point","title":"Adding support to quantity_point","text":"

    quantity_point is intended to model \"point\" quantities and return \"delta\" quantities on subtraction or by calling .quantity_from...() family of member functions. This is possible and can be done. I've finished most of the implementation already. However, two interesting questions arise:

    1. Should isq::altitude be reserved only for quantity_point and not available for \"regular\"\u00a0quantity types?
    2. Should isq::height apply only to quantity?

    I think that question #1 makes a lot of sense. If we realize that quantity always represents \"delta\" quantities, what would a quantity of isq::altitude mean? However, forcing the usage of quantity_point might be too strict here. Some users are not familiar or comfortable with this abstraction. Also, we can't multiply or divide quantity points.

    Question

    Does anyone know a derived quantity built with altitude or time instant? If so, please let me know in the comments, as limiting \"point\" quantity_spec to quantity_point would prevent forming such derived quantities.

    Question #2 is also interesting. However, in this case, I think that the answer should be \"NO\". I can imagine a series of height measurements. Every physical measurement can be modeled as a quantity_point, so a quantity_point of height might make sense.

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#opening-can-of-worms","title":"Opening can of worms","text":"

    So far, so good. I thought I was done here and could continue my work on symbolic expressions for vector and complex quantities. However, I've realized that I've opened a can of worms. What about the convertibility of quantity_spec? How should common_quantity_spec() behave?

    Let's start with conversions. It might seem easy. isq::altitude and isq::height should not be convertible to each other. But more questions arise:

    1. Should it be possible to quantity_cast from isq::altitude to isq::height or vice versa?
    2. Should isq::height be convertible to isq::length?
    3. Should isq::length be explicitly convertible to isq::height?
    4. Should isq::altitude be convertible to isq::length?
    5. Should isq::length be explicitly convertible to isq::altitude?

    The need for #1 will always probably mean an error in program logic, so quantity_cast could not work for such entities. This would be an exception to our conversion rules that always allow casting between branches of one tree.

    The answer to questions #2 and #3 is \"YES\".

    We might be tempted to say \"NO\" to questions #4 and #5 as isq::altitude is defined as \"point\" while isq::length is not specified as such. However, I've just realized that it is not the case.

    The proper answer to questions #4 and #5 is \"It depends\". If we are dealing with a quantity_point then converting from isq::altitude to isq::length or the other way around should work. However, it would probably be a bad idea for a quantity type.

    It turns out that common_quantity_spec() is similar. It is probably safe to state that it should not compile for isq::altitude and isq::height arguments. This means that we will not be able to compare such quantities as well. As those are different abstractions, preventing that might be an excellent idea.

    Again, it gets tricky if we consider passing isq::length and isq::altitude to it. For quantity_point it probably should work fine and fail to compile for quantity.

    The above means that to determine the conversion rules and common quantity specifications, we need to know the context in which the quantity_spec is being used. This sucks!

    "},{"location":"blog/2025/01/15/bringing-quantity-safety-to-the-next-level/#should-we-get-rid-of-a-quantity_point","title":"Should we get rid of a quantity_point?","text":"

    There are at least two ways of solving the above issue. In any case, we need to introduce a wrapper over the quantity_spec to denote it is being used in a \"point\" abstraction.

    A simpler solution could be implicitly amending the Reference provided to the quantity_point class template with point<...>. So, for example, we would have the following members in quantity_point<isq::altitude[m]>:

    This should work but might be a bit confusing as members of the class template would not exactly contain the types of template parameters.

    A better solution might be removing a dedicated quantity_point abstraction and providing both functionalities through the quantity class template. I still haven't figured out the best syntax. Please let me know if you have good ideas in the comments below. Here are some rough ideas:

    Before After quantity_spec quantity<si::metre> quantity<si::metre> kind_of<isq::length> quantity_point<si::metre> quantity<point<si::metre>> point<kind_of<isq::length>> quantity_point<si::metre, mean_sea_level> quantity<point<si::metre, mean_sea_level>> point<kind_of<isq::length>> quantity<isq::height[m]> quantity<isq::height[m]> isq::height quantity_point<isq::height[m]> quantity<point<isq::height[m]>> point<isq::height> quantity_point<isq::altitude[m]> quantity<point<isq::altitude[m]>> point<isq::altitude> quantity_point<isq::altitude[m], mean_sea_level> quantity<point<isq::altitude[m], mean_sea_level>> point<isq::altitude>

    I am still undecided about whether we should pursue this option, which would involve a huge design change in the library. It may even require bumping the library major version to V3.

    On the bright side, it would limit the number of abstractions in the library. It would also make the library more consistent with standards like ISO/IEC 80000, which talk about quantities and do not mention quantity points at all. This could also be useful before we start our work on the next big task - logarithmic quantities and units.

    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/","title":"Introducing absolute quantities","text":"

    This post introduces a new abstraction called an absolute quantity. It complements affine space abstractions (point and delta) and will most probably be a new default in the library when we release V3.

    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#affine-space-in-a-nutshell","title":"Affine space in a nutshell","text":"

    So far mp-units and other quantities and units libraries have been modeling two kinds of abstractions:

    1. Points (modeled with quantity_point class template)

      • can be interpolated,
      • can be subtracted,
      • can't be added,
      • can't be multiplied or divided by another quantity or scalar,
      • some of them could be specified as non-negative,
      • specified relative to some absolute or relative point origin,
      • conversion to offset units (e.g., degree Celsius) accounts for offset.

    2. Deltas (modeled with quantity class template)

      • can be interpolated,
      • can be subtracted,
      • can be added,
      • can be multiplied and divided by another quantity and scalar,
      • may be negative as there is always a chance that we will subtract a larger value from a smaller one,
      • don't use point origins in its definition,
      • conversion to offset units (e.g., degree Celsius) ignores the offset (just the conversion factor is used).

    Info

    More information on this subject can be found in the Affine Space chapter.

    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#issues","title":"Issues","text":"

    A current affine space implementation works well for many essential use cases. However, it also produces some issues.

    1. We can't print quantity points as, at least for today, we do not have the means to properly describe the user-provided origin in the text output.
    2. Quantity points are hard to use in physical equations to denote not-delta values.

    To make both of the above work, a user needs to convert the quantity point to quantity with either qp.quantity_from_zero() or qp.quantity_from(some_origin) member functions.

    quantity_point m1(2 * kg);\nquantity_point m2(3 * kg);\nquantity_point m = m1 + m2.quantity_from_zero();\nquantity d_v = 30 * km / h;\nquantity E_k = m.quantity_from_zero() * pow<2>(d_v) / 2;\n\nstd::cout << \"Mass: \" << m.quantity_from_zero() << \"\\n\";\nstd::cout << \"Velocity: \" << d_v << \"\\n\";\nstd::cout << \"Kinetic energy: \" << E_k.in<double>(J) << \"\\n\";\n

    This is quite inconvenient and is a common reason for avoiding quantity point abstraction in many equations in source code where it would be a good fit otherwise.

    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#absolute-quantities","title":"Absolute quantities","text":"

    Despite the above drawbacks, affine space points are necessary to model some abstractions (e.g., temperatures in degrees Celsius, tared mass measurements, altitudes above some reference point, etc.) and do it really well. Constrained affine space arithmetic (e.g., preventing accidental addition of points) also improves the safety of our programs. This is why it is a valuable abstraction and should be used more even often than now.

    To improve the user experience and open the doors for new features in the future, we are considering adding a third abstraction for absolute quantities. In terms of properties, an absolute quantity will lie between points and deltas.

    Feature Point Absolute Delta Interpolation Subtraction Addition Multiply/Divide May be non-negative Relative to origin Absolute & relative Measured against nothing/void Can use offset units Conversion to offset units With offset No offset Text output

    As we can see above, absolute quantities have only two limitations, and both are connected to the offset units' usage. They can't use those because they must remain absolute instead of being measured relative to some custom origin.

    Absolute quantities could be considered delta quantities that represent a whole -- the entire entity being measured. This is why we can represent a system mass by adding absolute masses of all system elements or a system energy by adding absolute temperatures of all the system elements.

    As those are more related to deltas than points, it is impossible to specify their origin points. This also allows us to print them, as we do not need any special text to describe their origin as they are always measured against nothing/void.

    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#interfaces-refactoring","title":"Interfaces refactoring","text":"

    As I mentioned in my previous post, we are seriously considering removing quantity_point class template and replacing it with a quantity_spec point wrapper. For example, quantity_point<isq::altitude[m]> will become quantity<point<isq::altitude[m]>>.

    I initially planned quantity<isq::mass> to be the same as quantity<delta<isq::mass>>, but it turns out that deltas probably should not be the default. It is consistent with how we write physical expressions on paper, right? Delta symbol (\u2206) is always \"verbose\" in physical equations, it would be nice for the C++ code to do the same. So, deltas will always need to be explicit.

    And this brings us to absolute quantities. They should actually be the default we are looking for. This is what we write as quantities in most of the physical equations. This is why we will not need any specifier to denote them.

    For example:

    inline constexpr struct tare final : relative_point_origin<quantity_point{2 * kg}> {} tare;\n\nquantity<point<isq::mass>>       m1(10 * kg);         // point quantity with an implicit point origin\nquantity<point<isq::mass, tare>> m2 = tare + 8 * kg;  // point quantity with an explicit relative point origin\nquantity<isq::mass> \u00a0 \u00a0 \u00a0 \u00a0      m3 = 15 * kg;        // absolute quantity (e.g., non-negative)\nquantity<delta<isq::mass>>       m13 = m1 - m3;       // delta quantity (e.g., may be negative)\nquantity<delta<isq::mass>>       m23 = m2 - m3;       // delta quantity (e.g., may be negative)\n

    With the above, the initial example may be refactored to:

    quantity m1 = 2 * kg;\nquantity m2 = 3 * kg;\nquantity m = m1 + m2;\nquantity d_v = delta<km / h>(30);\nquantity E_k = m * pow<2>(d_v) / 2;\n\nstd::cout << \"Mass: \" << m << \"\\n\";\nstd::cout << \"Velocity: \" << d_v << \"\\n\";\nstd::cout << \"Kinetic energy: \" << E_k.in<double>(J) << \"\\n\";\n
    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#arithmetic","title":"Arithmetic","text":"

    Affine space arithmetic is well-defined. However, we are adding a new type to the library that lands between points and deltas. This is why we must agree on the arithmetic for all possible combinations.

    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#addition","title":"Addition","text":"

    Absolute quantities are deltas against nothing so adding them to a point yields another point.

    Adding a delta to them yields a delta, as a delta may represent only a part of something and a whole, and a part is not a whole. The delta may also be negative and greater than the absolute quantity, which may yield a negative value. This is why delta is a good result here.

    Only adding whole non-negative entities of the system yields a system being expressed as an entire non-negative entity. This is why adding absolute quantities results in an absolute quantity.

    Lhs \\ Rhs Point Absolute Delta Point Point Point Absolute Point Absolute Delta Delta Point Delta Delta"},{"location":"blog/2025/06/16/introducing-absolute-quantities/#subtraction","title":"Subtraction","text":"

    Similarly, during subtraction, regular affine space arithmetics for deltas apply. Subtracting an absolute quantity from a point yields a point, and trying to do the opposite does not make physical sense.

    Subtracting two non-negative absolute quantities may yield a negative value if we subtract a larger one from the smaller one, so the result should be a delta. A similar result may be obtained by subtracting a delta from absolute quantity or absolute quantity from a delta.

    Lhs \\ Rhs Point Absolute Delta Point Delta Point Point Absolute Delta Delta Delta Delta Delta

    Info

    Based on the above assumptions, one of the lines of the below code can't compile:

    quantity temp1 = 270 * K;\nquantity temp2 = point<K>(300);\nquantity temp3 = temp2 - temp1;             // Point\n// quantity temp4 = temp1 - temp2;          // Compile-time error\nquantity temp5 = temp1 - temp2.absolute();  // Delta\n
    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#motivating-example","title":"Motivating example","text":"

    Let's consider a room with a table and two glasses filled with fluid on top of it. Let's also assume that we want to stack one on top of the other and treat them as a system we observe.

    // absolute quantities\nquantity<isq::height[cm]> glass1_height = 20 * cm;\nquantity<isq::height[cm]> glass2_height = 15 * cm;\n\n// delta quantities\nquantity<delta<isq::height>[cm]> fluid_level = 16 * cm;\n\n// point quantities\ninline constexpr struct floor_level final : absolute_point_origin<isq::height> floor_level;\nquantity<point<isq::height[cm], floor_level>> table_top = floor_level + 1 * m;\n\n// absolute results\nquantity system_height = glass1_height + glass2_height;\n\n// delta results\nquantity empty_height_res = glass1_height - fluid_level;\nquantity glass2_height_res = system_height - glass1_height;    // could result in an absolute quantity\nassert(glass2_height_res == glass2_height);\nquantity height_diff_res = glass2_height - glass1_height;      // but this one should definitely return delta\n\n// point results\nquantity<point<isq::height[cm], floor_level>> glass1_top = table_top + glass1_height;\nquantity point1 = glass1_top - glass1_height;\nassert(point1 == table_top);\n// quantity point2 = glass1_height - glass1_top; \u00a0 \u00a0          \u00a0// no sense - does not compile\n
    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#what-about-time","title":"What about time?","text":"

    Everything looks promising and nice for now. But let's look closer into the quantity of time. There is no way to measure its absolute value as we don't even know where (when?) the time axis starts... Only time points and time deltas (durations) make sense.

    The above raises a few questions:

    1. Does it mean that quantity<si::seconds> or quantity<isq::time[s]> should not compile?
    2. Should we require the user to always state quantity<delta<si::seconds>> or \u00a0 \u00a0quantity<delta<isq::time[s]>>? This would be consistent with physical equations but more verbose in the source code.
    3. Should the syntax 40 * s be disallowed or should it implicitly createquantity<delta<si::seconds>> instead of quantity<si::seconds>?
    4. A somehow similar case might be the length quantity as there is no one well-established zero origin that serves for all length measurements. However, asking the users always to provide a delta specifier for length would probably be an overkill.

    As you can see, I do not yet have good answers to the above problems yet. Please feel welcome to share some feedback on this.

    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#new-opportunities","title":"New opportunities","text":"

    The new syntax simplifies API as one quantity class template will now serve all quantity variations (possibly even more in the future). It also allows us to model quantities that were impossible to express before without some workarounds.

    For example, we can now correctly calculate Carnot engine efficiency with any of the following:

    quantity temp_cold = 300. * K;\nquantity temp_hot = 500. * K;\nquantity carnot_eff_1 = 1. - temp_cold / temp_hot;\nquantity carnot_eff_2 = (temp_hot - temp_cold) / temp_hot;\n

    In the above code, we can easily create absolute or delta values of temperatures and do arithmetics on them. Previously, we had to create deltas from both points artificially with:

    quantity temp_cold = point<K>(300.);\nquantity temp_hot = point<K>(500.);\nquantity carnot_eff_1 = 1. - temp_cold.quantity_from_zero() / temp_hot.quantity_from_zero();\nquantity carnot_eff_2 = (temp_hot - temp_cold) / temp_hot.quantity_from_zero();\n

    It worked but was far from being physically pure and pretty.

    "},{"location":"blog/2025/06/16/introducing-absolute-quantities/#summary","title":"Summary","text":"

    We believe that adding absolute quantities will be a significant improvement in the library that will allow us to model physical equations in a terser, more correct, easier to write, understand, and maintain way.

    We plan to deliver the features mentioned in this post as a part of mp-units V3.

    Please share your feedback.

    "},{"location":"blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/","title":"International System of Quantities (ISQ): Part 1 - Introduction","text":"

    This post starts a series of articles about the International System of Quantities (ISQ). In this series, we will describe:

    "},{"location":"blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/#articles-from-this-series","title":"Articles from this series","text":""},{"location":"blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/#terms-and-definitions","title":"Terms and Definitions","text":"

    From our experience, many people, including experts in the domain, often tend to name things differently, or sometimes they use the same term while having a different meaning in mind. This is why it is essential to stick to one well-defined glossary of terms for metrology.

    The mp-units project consistently uses the official metrology vocabulary defined by the ISO and BIPM:

    The above are identical and contain the same set of definitions. We provide both to point out that the biggest institutions in standardizing metrology agree on the same vocabulary.

    "},{"location":"blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/#systems-of-quantities-vs-systems-of-units","title":"Systems of Quantities vs Systems of Units","text":"

    Here are the official definitions from our vocabulary:

    System of quantities

    A system of quantities is a set of quantities together with a set of noncontradictory equations relating those quantities.

    System of units

    A system of units is a set of base units and derived units, together with their multiples and submultiples, defined in accordance with given rules, for a given system of quantities.

    From the definition above, we can find out that the systems of quantities and units form a hierarchy:

    flowchart TD\n    system_of_quantities[\"System of Quantities\"]\n    system_of_quantities --- system_of_units1[System of Units #1]\n    system_of_quantities --- system_of_units2[System of Units #2]\n    system_of_quantities --- system_of_units3[System of Units #3]

    System of quantities defines quantities commonly used in engineering (e.g., length, time, mass, speed, energy, power, etc.) and relations between them. It does not assign any specific units to those quantities, though.

    Systems of units are the ones that assign units of measurement to quantities from a specific system of quantities they chose to model. Different systems of units are free to chose whatever they find suitable for specific quantities and do not have to be consistent/compatible with other such systems. For example:

    Both systems of units above agree on the unit of time, but chose different units for other quantities. In the above example, SI chose a non-prefixed unit of metre for a base quantity of length while CGS chose a scaled centimetre. On the other hand, SI chose a scaled kilogram over the gram used in the CGS. Those decisions also result in a need for different coherent units for derived quantities. For example:

    Quantity SI CGS length metre (m) centimetre (cm) mass kilogram (kg) gram (g) time second (s) second (s) force newton (N) dyne energy joule (J) erg pressure pascal (Pa) barye

    Often, there is no way to state which one is correct or which one is wrong. Each system of units has the freedom to choose whichever unit suits its engineering requirements and constraints the best for a specific quantity.

    "},{"location":"blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/#isq-vs-si","title":"ISQ vs SI","text":"

    Some of the systems of quantities and units have been used more over the years and have become more popular than others. Here are the official descriptions of the most popular systems used in engineering today:

    International System of Quantities (ISQ)

    The International System of Quantities (ISQ) is a system of quantities based on the seven base quantities: length, mass, time, electric current, thermodynamic temperature, amount of substance, and luminous intensity.

    International System of Units (SI)

    The International System of Units (SI) is a system of units, based on the International System of Quantities, their names and symbols, including a series of prefixes and their names and symbols, together with rules for their use, adopted by the General Conference on Weights and Measures (CGPM).

    "},{"location":"blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/#the-international-system-of-quantities-isq-standardization","title":"The International System of Quantities (ISQ) standardization","text":"

    The set of quantities constituting the ISQ is defined in the series of ISO 80000 and IEC 80000 standards under the general title \"Quantities and units\".

    ISO 80000:

    IEC 80000:

    "},{"location":"blog/2024/10/07/international-system-of-quantities-isq-part-1---introduction/#to-be-continued","title":"To be continued...","text":"

    In the next part of this series, we will describe typical issues with libraries that do not model systems of quantities.

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/","title":"International System of Quantities (ISQ): Part 2 - Problems when ISQ is not used","text":"

    This article is the next one in our series about the ISQ. After introducing the basic terms and systems, this article will talk about the issues we face when we base the quantities and units library on just units or dimensions.

    Note

    The issues described in this article do not apply to the mp-units library. Its interfaces, even if when we decide only to use simple quantities that only use units, those are still backed up by quantity kinds under the framework's hood.

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#articles-from-this-series","title":"Articles from this series","text":""},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#limitations-of-units-only-solutions","title":"Limitations of units-only solutions","text":"

    Units-only is not a good design for a quantities and units library. It works to some extent, but plenty of use cases can't be addressed, and for those that somehow work, we miss important safety improvements provided by additional abstractions in this article series.

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#no-way-to-specify-a-quantity-type-in-generic-interfaces","title":"No way to specify a quantity type in generic interfaces","text":"

    A common requirement in the domain is to write unit-agnostic generic interfaces. For example, let's try to implement a generic avg_speed function template that takes a quantity of any unit and produces the result. If we call it with distance in km and time in h, we will get km/h as a result, but if we call it with mi and h, we expect mi/h to be returned.

    template<Unit auto U1, typename Rep1, Unit auto U2, typename Rep2>\nauto avg_speed(quantity<U1, Rep1> distance, quantity<U2, Rep2> time)\n{\n  return distance / time;\n}\n\nquantity speed = avg_speed(120 * km, 2 * h);\n

    This function works but does not provide any type safety to the users. The function arguments can be easily reordered on the call site. Also, we do not get any information about the return type of the function or any safety measures to ensure that the function logic actually returns a quantity of speed.

    To improve safety, with a units-only library, we have to write the function in the following way:

    template<typename Rep1, typename Rep2>\nquantity<si::metre / si::second, decltype(Rep1{} / Rep2{})> avg_speed(quantity<si::metre, Rep1> distance,\n                                                                      quantity<si::second, Rep2> time)\n{\n  return distance / time;\n}\n\navg_speed(120 * km, 2 * h).in(km / h);\n

    Despite being safer, the above code decreased the performance because we always pay for the conversion at the function's input and output.

    Moreover, in a good library, the above code should not compile. The reason for this is that even though the conversion from km to m and from h to s is considered value-preserving, it is not true in the opposite direction. When we try to convert the result stored in an integral type from the unit of m/s to km/h, we will inevitably lose some data.

    We could try to provide concepts like ScaledUnitOf<si::metre> that would take a set of units while trying to constrain them somehow, but it leads to even more problems with the unit definitions. For example, are Hz and Bq just scaled versions of 1/s? If we constrain the interface to just prefixed units, then litre and a cubic metre or kilometre and mile will be incompatible. What about radian and steradian or a litre per 100 kilometre (popular unit of a fuel consumption) and a squared metre? Should those be compatible?

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#disjoint-units-of-the-same-quantity-type-do-not-work","title":"Disjoint units of the same quantity type do not work","text":"

    Sometimes, we need to define several units describing the same quantity but which should not convert to each other in the library's framework. A typical example here is currency. A user may want to define EURO and USD as units of currency, so both of them can be used for such quantities. However, it is impossible to predefine one fixed conversion factor for those, as a currency exchange rate varies over time, and the library's framework can't provide such an information as an input to the built-in conversion function. User's application may have more information in this domain and handle such a conversion at runtime with custom logic (e.g., using an additional time point function argument). If we would like to model that in a unit-only solution, how can we specify that EURO and USD are units of quantities of currency, but are not convertible to each other?

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#dimensions-to-the-rescue","title":"Dimensions to the rescue?","text":"

    To resolve the above issues, most of the libraries on the market introduce dimension abstraction. Thanks to that, we could solve the first issue of the previous chapter with:

    QuantityOf<dim_speed> auto avg_speed(QuantityOf<dim_length> auto distance,\n                                     QuantityOf<dim_time> auto time)\n{\n  return distance / time;\n}\n

    and the second one by specifying that both EURO and USD are units of dim_currency. This is a significant improvement but still has some issues.

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#limitations-of-dimensions","title":"Limitations of dimensions","text":"

    Let's first look at the above solution again. A domain expert seeing this code will immediately say there is no such thing as a speed dimension. The ISQ specifies only 7 dimensions with unique symbols assigned, and the dimensions of all the ISQ quantities are created as a vector product of those. For example, a quantity of speed has a dimension of \\(L^1T^{-1}\\). So, to be physically correct, the above code should be rewritten as:

    QuantityOf<dim_length / dim_time> auto avg_speed(QuantityOf<dim_length> auto distance,\n                                                 QuantityOf<dim_time> auto time)\n{\n  return distance / time;\n}\n

    Most of the libraries on the market ignore this fact and try to model distinct quantities through their dimensions, giving a false sense of safety. A dimension is not enough to describe a quantity. This has been known for a long time now. The \"Measurement Data (Archive Report)\" report from 1996 says explicitly:

    Measurement Data (Archive Report)

    Dimensional analysis does not adequately model the semantics of measurement data.

    In the following chapters, we will see a few use cases that can't be solved with an approach that only relies on units or dimensions.

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#si-units-of-quantities-of-the-same-dimension-but-different-kinds","title":"SI units of quantities of the same dimension but different kinds","text":"

    The SI provides several units for distinct quantities of the same dimension but different kinds. For example:

    There are many more similar examples in the ISO/IEC 80000 series. For example, storage capacity quantity can be measured in units of one, bit, octet, and byte.

    The above conflicts can't be solved with dimensions, and they yield many safety issues. For example, we can ask ourselves what should be the result of the following:

    1. quantity q = 1 * Hz + 1 * Bq;
    2. quantity<Gy> q = 42 * Sv;
    3. bool b = (1 * rad + 1 * bit) == 2 * sr;

    None of the above code should compile, but most of the libraries on the market happily accept it and provide meaningless results. Some of them decide not to define one or more of the above units at all to avoid potential safety issues. For example, the Au library does not define Sv to avoid mixing it up with Gy.

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#derived-quantities-of-the-same-dimension-but-different-kinds","title":"Derived quantities of the same dimension but different kinds","text":"

    Even if some quantities do not have a specially assigned unit, they may still have a totally different physical meaning even if they share the same dimension:

    Again, we don't want to accidentally mix those.

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#various-quantities-of-the-same-dimension-and-kinds","title":"Various quantities of the same dimension and kinds","text":"

    Even if we somehow address all the above, there are plenty of use cases that still can't be safely implemented with such abstractions.

    Let's consider that we want to implement a freight transport application to position cargo in the container. In majority of the products on the market we will end up with something like:

    class Box {\n  length length_;\n  length width_;\n  length height_;\npublic:\n  Box(length l, length w, length h): length_(l), width_(w), height_(h) {}\n  area floor() const { return length_ * width_; }\n  // ...\n};\n
    Box my_box(2 * m, 3 * m, 1 * m);\n

    Such interfaces are not much safer than just using plain fundamental types (e.g., double). One of the main reasons of using a quantities and units library was to introduce strong-type interfaces to prevent such issues. In this scenario, we need to be able to discriminate between length, width, and height of the package.

    A similar but also really important use case is in aviation. The current altitude is a totally different quantity than the distance to the destination. The same is true for forward speed and sink rate. We do not want to accidentally mix those.

    When we deal with energy, we should be able to implicitly construct it from a proper product of any mass, length, and time. However, when we want to calculate gravitational potential energy, we may not want it to be implicitly initialized from any expression of matching dimensions. Such an implicit construction should be allowed only if we multiply a mass with acceleration of free fall and height. All other conversions should have an explicit annotation to make it clear that something potentially unsafe is being done in the code. Also, we should not be able to assign a potential energy to a quantity of kinetic energy. However, both of them (possibly accumulated with each other) should be convertible to a mechanical energy quantity.

    mass m = 1 * kg;\nlength l = 1 * m;\ntime t = 1 * s;\nacceleration_of_free_fall g = 9.81 * m / s2;\nheight h = 1 * m;\nspeed v = 1 * m / s;\nenergy e = m * pow<2>(l) / pow<2>(t);                     // OK\npotential_energy ep1 = e;                                 // should not compile\npotential_energy ep2 = static_cast<potential_energy>(e);  // OK\npotential_energy ep3 = m * g * h;                         // OK\nkinetic_energy ek1 = m * pow<2>(v) / 2;                   // OK\nkinetic_energy ek2 = ep3 + ek1;                           // should not compile\nmechanical_energy me = ep3 + ek1;                         // OK\n

    Yet another example comes from the audio industry. In the audio software, we want to treat specific counts (e.g., beats, samples) as separate quantities. We could assign dedicated base dimensions to them. However, if we divide them by duration, we should obtain a quantity convertible to frequency and even be able to express the result in a unit of Hz. With the dedicated dimensions approach, this wouldn't work as the dimension of frequency is just \\(T^{-1}\\), which would not match the results of our dimensional equations. This is why we can't assign dedicated dimensions to such counts.

    The last example that we want to mention here comes from finance. This time, we need to model currency volume as a special quantity of currency. currency volume can be obtained by multiplying currency by the dimensionless market quantity. Of course, both currency and currency volume should be expressed in the same units (e.g., USD).

    None of the above scenarios can be addressed with just units and dimensions. We need a better abstraction to safely implement them.

    "},{"location":"blog/2024/10/14/international-system-of-quantities-isq-part-2---problems-when-isq-is-not-used/#to-be-continued","title":"To be continued...","text":"

    In the next part of this series, we will introduce the main ideas behind the International System of Quantities and describe how we can model it in the programming language.

    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/","title":"International System of Quantities (ISQ): Part 3 - Modeling ISQ","text":"

    The physical units libraries on the market typically only focus on modeling one or more systems of units. However, as we have learned, this is not the only system kind to model. Another, and maybe even more important, is a system of quantities. The most important example here is the International System of Quantities (ISQ) defined by ISO/IEC 80000.

    This article continues our series about the International System of Quantities. This time, we will learn about the main ideas behind the ISQ and describe how it can be modelled in a programming language.

    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#articles-from-this-series","title":"Articles from this series","text":""},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#dimension-is-not-enough-to-describe-a-quantity","title":"Dimension is not enough to describe a quantity","text":"

    Most of the products on the market are aware of physical dimensions. However, a dimension is not enough to describe a quantity. Let's repeat briefly some of the problems described in more detail in the previous article. For example, let's see the following implementation:

    class Box {\n  area base_;\n  length height_;\npublic:\n  Box(length l, length w, length h) : base_(l * w), height_(h) {}\n  // ...\n};\n\nBox my_box(2 * m, 3 * m, 1 * m);\n

    How do you like such an interface? It turns out that in most existing strongly-typed libraries this is often the best we can do.

    Another typical question many users ask is how to deal with work and torque. Both of those have the same dimension but are distinct quantities.

    A similar issue is related to figuring out what should be the result of:

    auto res = 1 * Hz + 1 * Bq + 1 * Bd;\n

    where:

    All of those quantities have the same dimension, namely \\(\\mathsf{T}^{-1}\\), but probably it is not wise to allow adding, subtracting, or comparing them, as they describe vastly different physical properties.

    If the above example seems too abstract, let's consider Gy (gray - unit of absorbed dose) and Sv (sievert - unit of dose equivalent), or radian and steradian. All of those quantities have the same dimensions.

    Another example here is fuel consumption (fuel volume divided by distance, e.g., 6.7 l/100km) and an area. Again, both have the same dimension \\(\\mathsf{L}^{2}\\), but probably it wouldn't be wise to allow adding, subtracting, or comparing a fuel consumption of a car and the area of a football field. Such an operation does not have any physical sense and should fail to compile.

    It turns out that the above issues can't be solved correctly without proper modeling of a system of quantities.

    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#quantities-of-the-same-kind","title":"Quantities of the same kind","text":"

    As it was described in the previous article, dimension is not enough to describe a quantity. We need a better abstraction to ensure the safety of our calculations. It turns out that ISO/IEC 80000 comes with the answer:

    ISO 80000-1:2009

    ISO Guide also explicitly states:

    ISO Guide

    Measurement units of quantities of the same quantity dimension may be designated by the same name and symbol even when the quantities are not of the same kind. For example, joule per kelvin and J/K are respectively the name and symbol of both a measurement unit of heat capacity and a measurement unit of entropy, which are generally not considered to be quantities of the same kind. However, in some cases special measurement unit names are restricted to be used with quantities of specific kind only. For example, the measurement unit \u2018second to the power minus one\u2019 (1/s) is called hertz (Hz) when used for frequencies and becquerel (Bq) when used for activities of radionuclides. As another example, the joule (J) is used as a unit of energy, but never as a unit of moment of force, i.e. the newton metre (N \u00b7 m).

    The above quotes from ISO provide answers to all the issues mentioned above and in the previous article.

    More than one quantity may be defined for the same dimension:

    Two quantities can't be added, subtracted, or compared unless they belong to the same kind. As frequency, activity, and modulation rate are of different kinds, the expression provided above should not compile.

    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#system-of-quantities-is-not-only-about-kinds","title":"System of quantities is not only about kinds","text":"

    ISO/IEC 80000 specifies hundreds of different quantities. Plenty of various kinds are provided, and often, each kind contains more than one quantity. It turns out that such quantities form a hierarchy of quantities of the same kind.

    For example, here are all quantities of the kind length provided in the ISO 80000-3:

    flowchart TD\n    length[\"<b>length</b><br>[m]\"]\n    length --- width[\"<b>width</b> / <b>breadth</b>\"]\n    length --- height[\"<b>height</b> / <b>depth</b> / <b>altitude</b>\"]\n    width --- thickness[\"<b>thickness</b>\"]\n    width --- diameter[\"<b>diameter</b>\"]\n    width --- radius[\"<b>radius</b>\"]\n    length --- path_length[\"<b>path_length</b>\"]\n    path_length --- distance[\"<b>distance</b>\"]\n    distance --- radial_distance[\"<b>radial_distance</b>\"]\n    length --- wavelength[\"<b>wavelength</b>\"]\n    length --- displacement[\"<b>displacement</b><br>{vector}\"]\n    displacement --- position_vector[\"<b>position_vector</b>\"]\n    radius --- radius_of_curvature[\"<b>radius_of_curvature</b>\"]

    Each of the above quantities expresses some kind of length, and each can be measured with meters, which is the unit defined by the SI for quantities of length. However, each has different properties, usage, and sometimes even a different character (position vector and displacement are vector quantities).

    Forming such a hierarchy helps us define arithmetics and conversion rules for various quantities of the same kind.

    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#converting-between-quantities-of-the-same-kind","title":"Converting between quantities of the same kind","text":"

    Based on the hierarchy above, we can define the following quantity conversion rules:

    1. Implicit conversions

      • Every width is a length.
      • Every radius is a width.
      static_assert(implicitly_convertible(isq::width, isq::length));\nstatic_assert(implicitly_convertible(isq::radius, isq::length));\nstatic_assert(implicitly_convertible(isq::radius, isq::width));\n

      Implicit conversions are allowed on copy-initialization:

      void foo(quantity<isq::length[m]> q);\n
      quantity<isq::width[m]> q1 = 42 * m;\nquantity<isq::length[m]> q2 = q1;  // implicit quantity conversion\nfoo(q1);                           // implicit quantity conversion\n

    2. Explicit conversions

      • Not every length is a width.
      • Not every width is a radius.
      static_assert(!implicitly_convertible(isq::length, isq::width));\nstatic_assert(!implicitly_convertible(isq::length, isq::radius));\nstatic_assert(!implicitly_convertible(isq::width, isq::radius));\nstatic_assert(explicitly_convertible(isq::length, isq::width));\nstatic_assert(explicitly_convertible(isq::length, isq::radius));\nstatic_assert(explicitly_convertible(isq::width, isq::radius));\n

      Explicit conversions are forced by passing the quantity to a call operator of a quantity_spec type or by calling quantity's explicit constructor:

      void foo(quantity<isq::height[m]> q);\n
      quantity<isq::length[m]> q1 = 42 * m;\nquantity<isq::height[m]> q2 = isq::height(q1);  // explicit quantity conversion\nquantity<isq::height[m]> q3(q1);                // direct initialization\nfoo(isq::height(q1));                           // explicit quantity conversion\n

    3. Explicit casts

      • height is never a width, and vice versa.
      • Both height and width are quantities of kind length.
      static_assert(!implicitly_convertible(isq::height, isq::width));\nstatic_assert(!explicitly_convertible(isq::height, isq::width));\nstatic_assert(castable(isq::height, isq::width));\n

      Explicit casts are forced with a dedicated quantity_cast function:

      void foo(quantity<isq::height[m]> q);\n
      quantity<isq::width[m]> q1 = 42 * m;\nquantity<isq::height[m]> q2 = quantity_cast<isq::height>(q1);  // explicit quantity cast\nfoo(quantity_cast<isq::height>(q1));                           // explicit quantity cast\n

    4. No conversion

      • time has nothing in common with length.
      static_assert(!implicitly_convertible(isq::time, isq::length));\nstatic_assert(!explicitly_convertible(isq::time, isq::length));\nstatic_assert(!castable(isq::time, isq::length));\n

      Even the explicit casts will not force such a conversion:

      void foo(quantity<isq::length[m]>);\n
      quantity<isq::length[m]> q1 = 42 * s;    // Compile-time error\nfoo(quantity_cast<isq::length>(42 * s)); // Compile-time error\n
    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#comparing-adding-and-subtracting-quantities-of-the-same-kind","title":"Comparing, adding, and subtracting quantities of the same kind","text":"

    ISO/IEC 80000 explicitly states that width and height are quantities of the same kind, and as such they:

    This means that we should be allowed to compare any quantities from the same tree (as long as their underlying representation types are comparable):

    static_assert(isq::radius(1 * m) == isq::height(1 * m));\n

    Also, based on our hierarchy above, the only reasonable result of 1 * width + 1 * height is 2 * length, where the result of length is known as a common quantity type. A result of such an equation is always the first common node in a hierarchy tree of the same kind. For example:

    static_assert((isq::width(1 * m) + isq::height(1 * m)).quantity_spec == isq::length);\nstatic_assert((isq::thickness(1 * m) + isq::radius(1 * m)).quantity_spec == isq::width);\nstatic_assert((isq::distance(1 * m) + isq::path_length(1 * m)).quantity_spec == isq::path_length);\n
    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#modeling-a-quantity-kind","title":"Modeling a quantity kind","text":"

    In the quantities and units library, we also need an abstraction describing an entire family of quantities of the same kind. Such quantities have not only the same dimension but also can be expressed in the same units.

    To annotate a quantity to represent its kind (and not just a hierarchy tree's root quantity) we introduced a kind_of<> specifier. For example, to express any quantity of length, we need to type kind_of<isq::length>.

    Important

    isq::length and kind_of<isq::length> are two different things.

    Such an entity behaves as any quantity of its kind. This means that it is implicitly convertible to any quantity in a tree.

    static_assert(!implicitly_convertible(isq::length, isq::height));\nstatic_assert(implicitly_convertible(kind_of<isq::length>, isq::height));\n

    Additionally, the result of operations on quantity kinds is also a quantity kind:

    static_assert(same_type<kind_of<isq::length> / kind_of<isq::time>, kind_of<isq::length / isq::time>>);\n

    However, if at least one equation's operand is not a quantity kind, the result becomes a \"strong\" quantity where all the kinds are converted to the hierarchy tree's root quantities:

    static_assert(!same_type<kind_of<isq::length> / isq::time, kind_of<isq::length / isq::time>>);\nstatic_assert(same_type<kind_of<isq::length> / isq::time, isq::length / isq::time>);\n

    Info

    Only a root quantity from the hierarchy tree or the one marked with is_kind specifier in the quantity_spec definition can be put as a template parameter to the kind_of specifier. For example, kind_of<isq::width> will fail to compile. However, we can call get_kind(q) to obtain a kind of any quantity:

    static_assert(get_kind(isq::width) == kind_of<isq::length>);\n
    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#how-do-systems-of-units-benefit-from-the-isq-and-quantity-kinds","title":"How do systems of units benefit from the ISQ and quantity kinds?","text":"

    Modeling a system of units is the most essential feature and a selling point of every physical units library. Thanks to that, the library can protect users from assigning, adding, subtracting, or comparing incompatible units and provide automated conversion factors between various compatible units.

    Probably all the libraries in the wild model the SI (or at least most of it), and many of them provide support for additional units belonging to various other systems (e.g., imperial).

    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#systems-of-units-are-based-on-systems-of-quantities","title":"Systems of units are based on systems of quantities","text":"

    Systems of quantities specify a set of quantities and equations relating to those quantities. Those equations do not take any unit or a numerical representation into account at all. In order to create a quantity, we need to add those missing pieces of information. This is where a system of units kicks in.

    The SI is explicitly stated to be based on the ISQ. Among others, it defines seven base units, one for each base quantity of ISQ. In the library, this is expressed by associating a quantity kind to a unit being defined:

    inline constexpr struct metre final : named_unit<\"m\", kind_of<isq::length>> {} metre;\n

    The kind_of<isq::length> above states explicitly that this unit has an associated quantity kind. In other words, si::metre (and scaled units based on it) can be used to express the amount of any quantity of kind length.

    Note

    For some systems of units (e.g., natural units), a unit may not have an associated quantity type. For example, if we define the speed of light constant as c = 1, we can define a system where both length and time will be measured in seconds, and speed will be a quantity measured with the unit one. In such case, the definition will look as follows:

    inline constexpr struct second final : named_unit<\"s\"> {} second;\n
    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#constraining-a-derived-unit-to-work-only-with-a-specific-derived-quantity","title":"Constraining a derived unit to work only with a specific derived quantity","text":"

    Some derived units are valid only for specific derived quantities. For example, SI specifies both hertz and becquerel derived units with the same unit equation \\(s^{-1}\\). However, it also explicitly states:

    SI

    The hertz shall only be used for periodic phenomena and the becquerel shall only be used for stochastic processes in activity referred to a radionuclide.

    This is why it is important for the library to allow constraining such units to be used only with a specific quantity kind:

    inline constexpr struct hertz final : named_unit<\"Hz\", one / second, kind_of<isq::frequency>> {} hertz;\ninline constexpr struct becquerel final : named_unit<\"Bq\", one / second, kind_of<isq::activity>> {} becquerel;\n

    With the above, hertz can only be used for frequencies, while becquerel should only be used for quantities of activity:

    quantity<isq::frequency[Hz]> q1 = 60 * Bq;   // Compile-time error\nquantity<isq::activity[Hz]> q2;              // Compile-time error\nquantity<isq::frequency[Hz]> q3 = 60 * Hz;   // OK\nstd::cout << q3.in(Bq) << \"\\n\";              // Compile-time error\n

    We know already that quantities of different kinds can't be compared, added, and subtracted. The following equation will not compile thanks to constraining derived units to be valid for specific kinds only:

    auto q = 1 * Hz + 1 * Bq;   // Fails to compile\n

    All of the above features improve the safety of our library and the products that are using it.

    "},{"location":"blog/2024/10/21/international-system-of-quantities-isq-part-3---modeling-isq/#to-be-continued","title":"To be continued...","text":"

    In the next part of this series, we will present how we can implement our ISQ model in a C++ programming language and we will point out some of the first issues that stand in our way.

    "},{"location":"blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/","title":"International System of Quantities (ISQ): Part 4 - Implementing ISQ","text":"

    Up until now, we have introduced the International System of Quantities and described how we can model its main aspects. This article will present how to implement those models in a programming language, and we will point out some of the first issues that stand in our way.

    In the previous article, we have already introduced a notion of quantity kind, provided kind_of<> specifier, and described how it helps in the modeling of the system of units (e.g., SI).

    Now, it is time to see how we can implement hierarchies of quantities of the same kind.

    "},{"location":"blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/#articles-from-this-series","title":"Articles from this series","text":""},{"location":"blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/#modeling-a-hierarchy-of-kind-length","title":"Modeling a hierarchy of kind length","text":"

    First, let's start with something easy - hierarchy of kind length. ISO 80000-3 does a good job of describing all relations between quantities in this case.

    We've seen this tree already:

    flowchart TD\n    length[\"<b>length</b><br>[m]\"]\n    length --- width[\"<b>width</b> / <b>breadth</b>\"]\n    length --- height[\"<b>height</b> / <b>depth</b> / <b>altitude</b>\"]\n    width --- thickness[\"<b>thickness</b>\"]\n    width --- diameter[\"<b>diameter</b>\"]\n    width --- radius[\"<b>radius</b>\"]\n    length --- path_length[\"<b>path_length</b>\"]\n    path_length --- distance[\"<b>distance</b>\"]\n    distance --- radial_distance[\"<b>radial_distance</b>\"]\n    length --- wavelength[\"<b>wavelength</b>\"]\n    length --- displacement[\"<b>displacement</b><br>{vector}\"]\n    displacement --- position_vector[\"<b>position_vector</b>\"]\n    radius --- radius_of_curvature[\"<b>radius_of_curvature</b>\"]

    This is how we can model it in C++:

    inline constexpr struct dim_length final          : base_dimension<\"L\"> {} dim_length;\n\ninline constexpr struct length final              : quantity_spec<dim_length> {} length;\ninline constexpr struct width final               : quantity_spec<length> {} width;\ninline constexpr auto breadth = width;\ninline constexpr struct height final              : quantity_spec<length> {} height;\ninline constexpr auto depth = height;\ninline constexpr auto altitude = height;\ninline constexpr struct thickness final           : quantity_spec<width> {} thickness;\ninline constexpr struct diameter final            : quantity_spec<width> {} diameter;\ninline constexpr struct radius final              : quantity_spec<width> {} radius;\ninline constexpr struct radius_of_curvature final : quantity_spec<radius> {} radius_of_curvature;\ninline constexpr struct path_length final         : quantity_spec<length> {} path_length;\ninline constexpr auto arc_length = path_length;\ninline constexpr struct distance final            : quantity_spec<path_length> {} distance;\ninline constexpr struct radial_distance final     : quantity_spec<distance> {} radial_distance;\ninline constexpr struct wavelength final          : quantity_spec<length> {} wavelength;\ninline constexpr struct displacement final        : quantity_spec<length, quantity_character::vector> {} displacement;\ninline constexpr struct position_vector final     : quantity_spec<displacement> {} position_vector;\n

    Thanks to the expressivity and power of C++ templates, we can specify all quantity properties in one line of code. In the above code:

    Note

    Some quantities may be specified to have complex scalar, vector, or tensor character (e.g., displacement). The quantity character can be set with the last parameter of quantity_spec.

    "},{"location":"blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/#modeling-a-hierarchy-of-kind-energy","title":"Modeling a hierarchy of kind energy","text":"

    Base quantities are simple. It is more complicated when we start modeling derived quantities. Let's try to model the hierarchy for energy.

    When we look into the ISO/IEC 80000 standards, this task immediately stops being as easy as the previous one. Derived quantity equations often do not automatically form a hierarchy tree, and ISO/IEC standards do not provide a clear answer to inter-quantity dependencies. This is why it is often not obvious what such a tree should look like.

    Even more, ISO explicitly states:

    ISO/IEC Guide 99

    The division of \u2018quantity\u2019 according to \u2018kind of quantity\u2019 is, to some extent, arbitrary.

    Let's try anyway. The below presents some arbitrary hierarchy of derived quantities of kind energy:

    flowchart TD\n    energy[\"<b>energy</b><br><i>(mass * length<sup>2</sup> / time<sup>2</sup>)</i><br>[J]\"]\n    energy --- mechanical_energy[\"<b>mechanical_energy</b>\"]\n    mechanical_energy --- potential_energy[\"<b>potential_energy</b>\"]\n    potential_energy --- gravitational_potential_energy[\"<b>gravitational_potential_energy</b><br><i>(mass * acceleration_of_free_fall * height)</i>\"]\n    potential_energy --- elastic_potential_energy[\"<b>elastic_potential_energy</b><br><i>(spring_constant * amount_of_compression<sup>2</sup>)</i>\"]\n    mechanical_energy --- kinetic_energy[\"<b>kinetic_energy</b><br><i>(mass * speed<sup>2</sup>)</i>\"]\n    energy --- enthalpy[\"<b>enthalpy</b>\"]\n    enthalpy --- internal_energy[\"<b>internal_energy</b> / <b>thermodynamic_energy</b>\"]\n    internal_energy --- Helmholtz_energy[\"<b>Helmholtz_energy</b> / <b>Helmholtz_function</b>\"]\n    enthalpy --- Gibbs_energy[\"<b>Gibbs_energy</b> / <b>Gibbs_function</b>\"]\n    energy --- active_energy[\"<b>active_energy</b>\"]

    As we can see above, besides what we've already seen for length hierarchy, derived quantities may provide specific recipes that can be used to create them implicitly:

    And here is the C++ code for it:

    inline constexpr struct energy final                         : quantity_spec<mass* pow<2>(length) / pow<2>(time)> {} energy;\ninline constexpr struct mechanical_energy final              : quantity_spec<energy> {} mechanical_energy;                                                            // differs from ISO 80000\ninline constexpr struct potential_energy final               : quantity_spec<mechanical_energy> {} potential_energy;                                                  // differs from ISO 80000\ninline constexpr struct gravitational_potential_energy final : quantity_spec<potential_energy, mass * acceleration_of_free_fall * height> {} potential_energy;        // not in ISO 80000\ninline constexpr struct elastic_potential_energy final       : quantity_spec<potential_energy, spring_constant * pow<2>(amount_of_compression)> {} potential_energy;  // not in ISO 80000\ninline constexpr struct kinetic_energy final                 : quantity_spec<mechanical_energy, mass* pow<2>(speed)> {} kinetic_energy;                               // differs from ISO 80000\ninline constexpr struct enthalpy final                       : quantity_spec<energy> {} enthalpy;                                                                     // differs from ISO 80000\ninline constexpr struct internal_energy final                : quantity_spec<enthalpy> {} internal_energy;                                                            // differs from ISO 80000\ninline constexpr auto thermodynamic_energy = internal_energy;\ninline constexpr struct Helmholtz_energy final               : quantity_spec<internal_energy> {} Helmholtz_energy;\ninline constexpr auto Helmholtz_function = Helmholtz_energy;\ninline constexpr struct Gibbs_energy final                   : quantity_spec<enthalpy> {} Gibbs_energy;\ninline constexpr auto Gibbs_function = Gibbs_energy;\n

    Again, the first parameter of quantity_spec determines the position in the tree. If a second argument is provided, it denotes a recipe for this quantity.

    With the above simple definitions we've automatically addressed our energy-related issues from the Various quantities of the same dimension and kinds chapter of the \"Part 2\" article.

    "},{"location":"blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/#modeling-a-hierarchy-of-kind-dimensionless","title":"Modeling a hierarchy of kind dimensionless","text":"

    As the last example for this article, let's try to model and implement quantities of dimension one, often also called dimensionless quantities. This quantity hierarchy contains more than one quantity kind and more than one unit in its tree:

    flowchart TD\n    dimensionless[\"<b>dimensionless</b><br>[one]\"]\n    dimensionless --- rotation[\"<b>rotation</b>\"]\n    dimensionless --- thermodynamic_efficiency[\"<b>thermodynamic_efficiency</b><br><i>(work / heat)</i>\"]\n    dimensionless --- angular_measure[\"<b>angular_measure</b><br><i>(arc_length / radius)</i><br>[rad]\"]\n    angular_measure --- rotational_displacement[\"<b>rotational_displacement</b><br><i>(path_length / radius)</i>\"]\n    angular_measure --- phase_angle[\"<b>phase_angle</b>\"]\n    dimensionless --- solid_angular_measure[\"<b>solid_angular_measure</b><br><i>(area / pow<2>(radius))</i><br>[sr]\"]\n    dimensionless --- drag_factor[\"<b>drag_factor</b><br><i>(drag_force / (mass_density * pow<2>(speed) * area))</i>\"]\n    dimensionless --- storage_capacity[\"<b>storage_capacity</b><br>[bit]\"] --- equivalent_binary_storage_capacity[\"<b>equivalent_binary_storage_capacity</b>\"]\n    dimensionless --- ...

    To enable such support in the library, we provided an is_kind specifier that can be appended to the quantity specification:

    inline constexpr struct dimensionless final            : quantity_spec<detail::derived_quantity_spec<>{}> {} dimensionless;\ninline constexpr struct rotation final                 : quantity_spec<dimensionless> {} rotation;\ninline constexpr struct thermodynamic_efficiency final : quantity_spec<dimensionless, work / heat> {} efficiency;\ninline constexpr struct angular_measure final          : quantity_spec<dimensionless, arc_length / radius, is_kind> {} angular_measure;\ninline constexpr struct rotational_displacement final  : quantity_spec<angular_measure, path_length / radius> {} rotational_displacement;\ninline constexpr struct phase_angle final              : quantity_spec<angular_measure> {} phase_angle;\ninline constexpr struct solid_angular_measure final    : quantity_spec<dimensionless, area / pow<2>(radius), is_kind> {} solid_angular_measure;\ninline constexpr struct drag_factor final              : quantity_spec<dimensionless, drag_force / (mass_density * pow<2>(speed) * area)> {} drag_factor;\ninline constexpr struct storage_capacity final         : quantity_spec<dimensionless, is_kind> {} storage_capacity;\n

    With the above, we can constrain radian, steradian, and bit to be allowed for usage with specific quantity kinds only:

    inline constexpr struct radian final    : named_unit<\"rad\", metre / metre, kind_of<isq::angular_measure>> {} radian;\ninline constexpr struct steradian final : named_unit<\"sr\", square(metre) / square(metre), kind_of<isq::solid_angular_measure>> {} steradian;\ninline constexpr struct bit final       : named_unit<\"bit\", one, kind_of<storage_capacity>> {} bit;\n

    but still allow the usage of one and its scaled versions for such quantities.

    Note

    dimensionless is a special quantity which serves as an identity element in quantity equations. It is predefined in the library's framework and there is no way for the user to define it or something similar to it.

    "},{"location":"blog/2024/10/28/international-system-of-quantities-isq-part-4---implementing-isq/#to-be-continued","title":"To be continued...","text":"

    In the next part of this series, we will present how our ISQ model helps to address the remaining issues described in the Part 2 of our series.

    "},{"location":"blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/","title":"International System of Quantities (ISQ): Part 5 - Benefits","text":"

    In the previous articles, we introduced the International System of Quantities, described how we can model and implement it in a programming language, and presented the issues of software that does not use such abstraction to implement a units library.

    Some of the issues raised in Part 2 of our series were addressed in Part 3 already. This article will present how our ISQ model elegantly addresses the remaining problems.

    "},{"location":"blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/#articles-from-this-series","title":"Articles from this series","text":""},{"location":"blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/#generic-but-safe-interfaces","title":"Generic but safe interfaces","text":"

    Let's start with the implementation of a generic utility function that would calculate the average speed based on provided arguments. The resulting quantity should use a derived unit of the provided arguments (e.g., km/h for km and h, m/s for m and s, ...).

    With C++ concepts backed up with ISQ quantities, we can simply type it as:

    constexpr QuantityOf<isq::speed> auto avg_speed(QuantityOf<isq::length> auto d,\n                                                QuantityOf<isq::time> auto t)\n{\n  return d / t;\n}\n

    The above constrains the algorithm to proper quantity types and ensures that a quantity of speed is returned. The latter is essential not only for the users to better understand what the function does but also serves as a unit test for our implementation. It ensures that our quantity equations are correct in the implementation part of the function, and we indeed return a quantity of speed.

    "},{"location":"blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/#non-convertible-units-of-currency","title":"Non-convertible units of currency","text":"

    Our second example was about disjoint units of currency. We want to use various units of currency but we can't provide compile-time known conversion factors between those as such ratios are only known at runtime.

    First, we define:

    inline constexpr struct dim_currency final : base_dimension<\"$\"> {} dim_currency;\ninline constexpr struct currency final : quantity_spec<dim_currency> {} currency;\n\ninline constexpr struct euro final : named_unit<\"EUR\", kind_of<currency>> {} euro;\ninline constexpr struct us_dollar final : named_unit<\"USD\", kind_of<currency>> {} us_dollar;\n\nnamespace unit_symbols {\n\ninline constexpr auto EUR = euro;\ninline constexpr auto USD = us_dollar;\n\n}\n\nstatic_assert(!std::equality_comparable_with<quantity<euro, int>, quantity<us_dollar, int>>);\n

    Next, we can provide a custom currency exchange facility that accounts for a specific point in time:

    template<Unit auto From, Unit auto To>\n[[nodiscard]] double exchange_rate(std::chrono::sys_seconds timestamp)\n{\n  // user-provided logic...\n}\n\ntemplate<UnitOf<currency> auto To, QuantityOf<currency> From>\nQuantityOf<currency> auto exchange_to(From q, std::chrono::sys_seconds timestamp)\n{\n  const auto rate =\n    static_cast<From::rep>(exchange_rate<From::unit, To>(timestamp) * q.numerical_value_in(q.unit));\n  return rate * From::quantity_spec[To];\n}\n

    Finally, we can use our simple model in the following way:

    using namespace unit_symbols;\nusing namespace std::chrono;\n\nconst auto yesterday = time_point_cast<seconds>(system_clock::now() - hours{24});\nconst quantity price_usd = 100 * USD;\nconst quantity price_euro = exchange_to<euro>(price_usd, yesterday);\n\nstd::cout << price_usd << \" -> \" << price_euro << \"\\n\";\n// std::cout << price_usd + price_euro << \"\\n\";  // does not compile\n

    Note

    It would be better to model the above prices as quantity points, but this is a subject for a different article .

    "},{"location":"blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/#derived-quantities-of-the-same-dimension-but-different-kinds","title":"Derived quantities of the same dimension but different kinds","text":"

    Until now, the issues discussed have not actually required modeling of the ISQ. The introduction of physical dimensions would be enough, and indeed, this is what most of the libraries on the market do. However, we have more exciting challenges to solve as well.

    The next issue was related to different quantities having the same dimension. In many cases, we want to prevent conversions and any other compatibility between such distinct quantities.

    Let's try to implement our fuel consumption example. First, we define the quantity type and a handy identifier for a derived unit that we want to use:

    inline constexpr struct fuel_consumption final : quantity_spec<isq::volume / isq::length> {} fuel_consumption;\ninline constexpr auto L_per_100km = si::litre / (mag<100> * si::kilo<si::metre>);\n\nstatic_assert(fuel_consumption != isq::area);\nstatic_assert(fuel_consumption.dimension == isq::area.dimension);\n

    Next, we define two quantities. The first one is based only on a derived unit of L/[100 km], while the second uses a strongly typed quantity type:

    quantity q1 = 5.8 * L_per_100km;\nquantity q2 = fuel_consumption(6.7 * L_per_100km);\nstd::println(\"Fuel consumptions: {}, {}\", q1, q2);\n\nstatic_assert(implicitly_convertible(q1.quantity_spec, isq::area));\nstatic_assert(!implicitly_convertible(q2.quantity_spec, isq::area));\nstatic_assert(!explicitly_convertible(q2.quantity_spec, isq::area));\nstatic_assert(!castable(q2.quantity_spec, isq::area));\n

    As we can see, with just units (especially derived ones) and dimensions, we often can't achieve the same level of safety as with adequately modeled hierarchies of quantities. Only in case of q2 we can prevent incorrect conversions to a different quantity of the same dimension.

    "},{"location":"blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/#various-quantities-of-the-same-dimension-and-kinds","title":"Various quantities of the same dimension and kinds","text":"

    In the previous example, area and fuel consumption were quantities of the same dimension but of different kinds. In engineering, there are also many cases where we need to model distinct quantities of the same kind.

    Let's try to improve the safety of our Box example.

    First, we need to extend our ISQ definitions by the horizontal length quantity and a horizontal area derived from it:

    inline constexpr struct horizontal_length final : quantity_spec<isq::length> {} horizontal_length;\ninline constexpr struct horizontal_area final : quantity_spec<isq::area, horizontal_length * isq::width> {} horizontal_area;\n

    Note

    isq::length denotes any quantity of length (not only the horizontal one).

    static_assert(implicitly_convertible(horizontal_length, isq::length));\nstatic_assert(!implicitly_convertible(isq::length, horizontal_length));\n\nstatic_assert(implicitly_convertible(horizontal_area, isq::area));\nstatic_assert(!implicitly_convertible(isq::area, horizontal_area));\n\nstatic_assert(implicitly_convertible(isq::length * isq::length, isq::area));\nstatic_assert(!implicitly_convertible(isq::length * isq::length, horizontal_area));\n\nstatic_assert(implicitly_convertible(horizontal_length * isq::width, isq::area));\nstatic_assert(implicitly_convertible(horizontal_length * isq::width, horizontal_area));\n

    With simple two lines of definition, we made the above logic automatically work without needing additional customization for special cases. Based on hierarchies of derived quantities and their recipes, the proposed model automatically inherits the properties of base quantities involved in the recipe. This makes the composition of derived quantities very easy, which is not true for alternative solutions based on tag types that do not compose their properties.

    Now we can refactor our Box to benefit from the introduced safe abstractions:

    class Box {\n  quantity<horizontal_length[m]> length_;\n  quantity<isq::width[m]> width_;\n  quantity<isq::height[m]> height_;\npublic:\n  Box(quantity<horizontal_length[m]> l, quantity<isq::width[m]> w, quantity<isq::height[m]> h):\n    length_(l), width_(w), height_(h)\n  {}\n\n  quantity<horizontal_area[m2]> floor() const { return length_ * width_; }\n  // ...\n};\n

    It is important to note that the safety can be enforced only when a user provides typed quantities as arguments to the functions:

    Box my_box1(2 * m, 3 * m, 1 * m);\nBox my_box2(2 * horizontal_length[m], 3 * isq::width[m], 1 * isq::height[m]);\nBox my_box3(horizontal_length(2 * m), isq::width(3 * m), isq::height(1 * m));\n

    Important

    It is up to the user to decide when and where to care about explicit quantity types and when to prefer simple unit-only mode.

    "},{"location":"blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/#various-kinds-of-dimensionless-quantities","title":"Various kinds of dimensionless quantities","text":"

    Most of the quantities hierarchies describe only one kind. There are some exceptions, though. One of them is a hierarchy of dimensionless quantities. This tree defines quantities that denote:

    Each of the above could form a separate tree of mutually comparable quantities. However, all of them have a common property. Every quantity from this tree, despite often being measured in a dedicated unit (e.g., bit, rad, sr), should also be able to be measured in a unit one.

    We've seen how to model such a hierarchy in a previous article in our series. This time, we will see a simplified part of a concrete, real-life example for this use case.

    We often need to provide strong types for different counts in the digital signal processing domain. Abstractions like samples, beats, MIDI clock, and others should not be possible to be intermixed with each other:

    namespace ni {\n\ninline constexpr struct SampleCount final : quantity_spec<dimensionless, is_kind> {} SampleCount;\ninline constexpr struct UnitSampleAmount final : quantity_spec<dimensionless, is_kind> {} UnitSampleAmount;\ninline constexpr struct MIDIClock final : quantity_spec<dimensionless, is_kind> {} MIDIClock;\ninline constexpr struct BeatCount final : quantity_spec<dimensionless, is_kind> {} BeatCount;\n

    We should also be able to create derived quantities from those. For example, when we divide such a quantity by time we should get a new strong quantity that can be measured in both a dedicated unit (e.g., Smpl/s for sample rate) and hertz:

    inline constexpr struct SampleDuration final : quantity_spec<isq::period_duration> {} SampleDuration;\ninline constexpr struct SamplingRate final : quantity_spec<isq::frequency, SampleCount / SampleDuration> {} SamplingRate;\n\ninline constexpr auto Amplitude = UnitSampleAmount;\ninline constexpr auto Level = UnitSampleAmount;\ninline constexpr struct Power final : quantity_spec<Level * Level> {} Power;\n\ninline constexpr struct BeatDuration final : quantity_spec<isq::period_duration> {} BeatDuration;\ninline constexpr struct Tempo final : quantity_spec<isq::frequency, BeatCount / BeatDuration> {} Tempo;\n

    We can also define a collection of units associated with specific quantity kinds and their symbols:

    inline constexpr struct Sample final : named_unit<\"Smpl\", one, kind_of<SampleCount>> {} Sample;\ninline constexpr struct SampleValue final : named_unit<\"PCM\", one, kind_of<UnitSampleAmount>> {} SampleValue;\ninline constexpr struct MIDIPulse final : named_unit<\"p\", one, kind_of<MIDIClock>> {} MIDIPulse;\n\ninline constexpr struct QuarterNote final : named_unit<\"q\", one, kind_of<BeatCount>> {} QuarterNote;\ninline constexpr struct HalfNote final : named_unit<\"h\", mag<2> * QuarterNote> {} HalfNote;\ninline constexpr struct DottedHalfNote final : named_unit<\"h.\", mag<3> * QuarterNote> {} DottedHalfNote;\ninline constexpr struct WholeNote final : named_unit<\"w\", mag<4> * QuarterNote> {} WholeNote;\ninline constexpr struct EightNote final : named_unit<\"8th\", mag_ratio<1, 2> * QuarterNote> {} EightNote;\ninline constexpr struct DottedQuarterNote final : named_unit<\"q.\", mag<3> * EightNote> {} DottedQuarterNote;\ninline constexpr struct QuarterNoteTriplet final : named_unit<\"qt\", mag_ratio<1, 3> * HalfNote> {} QuarterNoteTriplet;\ninline constexpr struct SixteenthNote final : named_unit<\"16th\", mag_ratio<1, 2> * EightNote> {} SixteenthNote;\ninline constexpr struct DottedEightNote final : named_unit<\"q.\", mag<3> * SixteenthNote> {} DottedEightNote;\n\ninline constexpr auto Beat = QuarterNote;\n\ninline constexpr struct BeatsPerMinute final : named_unit<\"bpm\", Beat / si::minute> {} BeatsPerMinute;\ninline constexpr struct MIDIPulsePerQuarter final : named_unit<\"ppqn\", MIDIPulse / QuarterNote> {} MIDIPulsePerQuarter;\n\nnamespace unit_symbols {\n\ninline constexpr auto Smpl = Sample;\ninline constexpr auto pcm = SampleValue;\ninline constexpr auto p = MIDIPulse;\n\ninline constexpr auto n_wd = 3 * HalfNote;\ninline constexpr auto n_w = WholeNote;\ninline constexpr auto n_hd = DottedHalfNote;\ninline constexpr auto n_h = HalfNote;\ninline constexpr auto n_qd = DottedQuarterNote;\ninline constexpr auto n_q = QuarterNote;\ninline constexpr auto n_qt = QuarterNoteTriplet;\ninline constexpr auto n_8thd = DottedEightNote;\ninline constexpr auto n_8th = EightNote;\ninline constexpr auto n_16th = SixteenthNote;\n\n}\n\n}  // namespace ni\n

    With the above, we can safely work with each quantity and use SI or domain-specific units as needed:

    using namespace ni::unit_symbols;\nusing namespace mp_units::si::unit_symbols;\n\nconst auto sr1 = ni::GetSampleRate();\nconst auto sr2 = 48'000.f * Smpl / s;\n\nconst auto samples = 512 * Smpl;\n\nconst auto sampleTime1 = (samples / sr1).in(s);\nconst auto sampleTime2 = (samples / sr2).in(ms);\n\nconst auto sampleDuration1 = (1 / sr1).in(ms);\nconst auto sampleDuration2 = (1 / sr2).in(ms);\n\nconst auto rampTime = 35.f * ms;\nconst auto rampSamples1 = (rampTime * sr1).force_in<int>(Smpl);\nconst auto rampSamples2 = (rampTime * sr2).force_in<int>(Smpl);\n\nstd::println(\"Sample rate 1 is: {}\", sr1);\nstd::println(\"Sample rate 2 is: {}\", sr2);\n\nstd::println(\"{} @ {} is {::N[.5f]}\", samples, sr1, sampleTime1);\nstd::println(\"{} @ {} is {::N[.5f]}\", samples, sr2, sampleTime2);\n\nstd::println(\"One sample @ {} is {::N[.5f]}\", sr1, sampleDuration1);\nstd::println(\"One sample @ {} is {::N[.5f]}\", sr2, sampleDuration2);\n\nstd::println(\"{} is {} @ {}\", rampTime, rampSamples1, sr1);\nstd::println(\"{} is {} @ {}\", rampTime, rampSamples2, sr2);\n

    The above prints:

    Sample rate 1 is: 44100 Hz\nSample rate 2 is: 48000 Smpl/s\n512 Smpl @ 44100 Hz is 0.01161 s\n512 Smpl @ 48000 Smpl/s is 10.66667 ms\nOne sample @ 44100 Hz is 0.02268 ms\nOne sample @ 48000 Smpl/s is 0.02083 ms\n35 ms is 1543 Smpl @ 44100 Hz\n35 ms is 1680 Smpl @ 48000 Smpl/s\n

    We can also do a bit more advanced computations to get the following:

    auto sampleValue = -0.4f * pcm;\nauto power1 = sampleValue * sampleValue;\nauto power2 = -0.2 * pow<2>(pcm);\n\nauto tempo = ni::GetTempo();\nauto reverbBeats = 1 * n_qd;\nauto reverbTime = reverbBeats / tempo;\n\nauto pulsePerQuarter = value_cast<float>(ni::GetPPQN());\nauto transportPosition = ni::GetTransportPos();\nauto transportBeats = (transportPosition / pulsePerQuarter).in(n_q);\nauto transportTime = (transportBeats / tempo).in(s);\n\nstd::println(\"SampleValue is: {}\", sampleValue);\nstd::println(\"Power 1 is: {}\", power1);\nstd::println(\"Power 2 is: {}\", power2);\n\nstd::println(\"Tempo is: {}\", tempo);\nstd::println(\"Reverb Beats is: {}\", reverbBeats);\nstd::println(\"Reverb Time is: {}\", reverbTime.in(s));\nstd::println(\"Pulse Per Quarter is: {}\", pulsePerQuarter);\nstd::println(\"Transport Position is: {}\", transportPosition);\nstd::println(\"Transport Beats is: {}\", transportBeats);\nstd::println(\"Transport Time is: {}\", transportTime);\n

    which prints:

    SampleValue is: -0.4 PCM\nPower 1 is: 0.16000001 PCM\u00b2\nPower 2 is: -0.2 PCM\u00b2\nTempo is: 110 bpm\nReverb Beats is: 1 q.\nReverb Time is: 0.8181818 s\nPulse Per Quarter is: 960 ppqn\nTransport Position is: 15836 p\nTransport Beats is: 16.495832 q\nTransport Time is: 8.997726 s\n

    Info

    More about this example can be found in \"Exploration of Strongly-typed Units in C++: A Case Study from Digital Audio\" CppCon 2023 talk by Roth Michaels.

    "},{"location":"blog/2024/11/04/international-system-of-quantities-isq-part-5---benefits/#to-be-continued","title":"To be continued...","text":"

    In the next part of this series, we will discuss the challenges and issues related to the modeling of the ISQ with a programming language.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/","title":"International System of Quantities (ISQ): Part 6 - Challenges","text":"

    This article might be the last one from our series. This time, we will discuss the challenges and issues with modeling of the ISQ in software.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#articles-from-this-series","title":"Articles from this series","text":""},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#ambiguity","title":"Ambiguity","text":"

    Some quantity names are ambiguous. It is not a problem of ISQ but of the English language and the way we communicate things. When I say: \"Every width is a length, but not every length is a width\" most people understand this right away. However, the same people trying to model our 3D box problem try to do it as follows:

    class Box {\n  quantity<isq::length[m]> length_;\n  quantity<isq::width[m]> width_;\n  quantity<isq::height[m]> height_;\npublic:\n  // ...\n};\n

    This looks correct at first sight. Only when we think about the sentence mentioned above will we realize that this implementation has a problem. We intended to specify three orthogonal dimensions of the box, each of which will be a strong quantity that is not convertible to others. But we've failed.

    When we look at the tree of quantities of length we immediately see that both width and height are special lengths so they are convertible to it.

    To implement our task correctly, we had to define and use a new quantity of kind length:

    inline constexpr struct horizontal_length final : quantity_spec<isq::length> {} horizontal_length;\n

    We do not propose adding horizontal length to ISO 80000-3. There are probably other similar cases as well, but so far, this was the most common and obvious one we've encountered.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#no-common-quantities","title":"No common quantities","text":"

    ISO 80000-1:2009 explicitly states:

    Quote

    Two or more quantities cannot be added or subtracted unless they belong to the same category of mutually comparable quantities.

    This means that we should be able to add and subtract any quantities as long as they belong to the same kind. However, ISO/IEC documents do not provide any rules or even hints about what should be the result of such operations.

    If it is possible to add radius and distance, then what quantity should be provided in return? Undoubtedly, the resulting quantity type can't be the same as any of the arguments. It is not a radius or distance. It is some closer unspecified length, though.

    Info

    Finding the correct solution took us many months of experimentation and implementation. Based on the hierarchy tree of quantities, we can define conversion rules and what a common quantity should be.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#lack-of-consistency","title":"Lack of consistency","text":"

    The documents of ISO/IEC 80000 are not 100% consistent, and programming languages do not like inconsistencies.

    For example:

    To be consistent, ISO/IEC should either:

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#lack-of-definitions","title":"Lack of definitions","text":"

    ISQ defines derived quantities in terms of other quantities provided in the series. However, some definitions mention quantities that are not defined in the ISQ at all.

    For example, weight is defined as \\(F_\\textsf{g} = m\\;g\\), where \\(m\\) is the mass of the body (item 4-1 of ISO 80000-4 \"Mechanics\"), and \\(g\\) is the local acceleration of free fall (ISO 80000-3).

    The problem here is that ISO 80000-3 never defines a quantity with a symbol \\(g\\) or named as a local acceleration of free fall. The closest one we have is acceleration (item 3-11) with a symbol \\(a\\).

    Info

    To have a proper definition of weight in mp-units that is not defined in terms of just any kind of acceleration, we have added isq::acceleration_of_free_fall in our definitions as an extension to the original ISQ set of quantities.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#not-engineering-friendly","title":"Not engineering-friendly","text":"

    Many quantities have proper physical definitions, but they are sometimes not engineering-friendly.

    For example, velocity is defined as a rate of change of position vector \\(v = \\frac{\\textsf{d}r}{\\textsf{d}t}\\), where \\(r\\) denotes the position vector (item 3\u20111.10) and \\(t\\) the duration (item 3\u20119).

    Next, a speed quantity is defined as the magnitude of velocity. Despite being physically correct, requiring every speed to be derived from the vector quantity of velocity in software would be inconvenient. If this was the only case, people would always need to use vector representations of position vectors to talk about speeds, which differs from what we do in practice. In practice, we divide any kind of length by time to get some kind of speed.

    ISO 80000-3 provides length, height, distance and other quantities of kind length that when divided by duration can serve really well to calculate speed.

    Info

    This is why in mp-units, we decided to divert from the official definition of speed and define it as:

    inline constexpr struct speed : quantity_spec<speed, length / time> {} speed;\n

    This allows us to create a quantity of kind speed from any quantity of length divided by time.

    Additionally, it is essential to note that for the needs of our library, defining velocity as position_vector / duration would be wrong. We miss the delta part here. Even though it is not mentioned in ISO 80000-3, the delta of position vectors is actually a displacement. This is why our velocity is defined as:

    inline constexpr struct velocity : quantity_spec<speed, displacement / duration> {} velocity;\n

    Please also note that velocity is defined as a more specialized quantity of speed.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#affine-space-agnostic","title":"Affine space agnostic","text":"

    The affine space is a powerful abstraction, allowing us to model some problems safer or more accurately. It has two types of entities:

    Vectors support all the arithmetics operations, but points have some limitations. It is not possible to:

    ISO/IEC series does not acknowledge this abstraction even though it would be really useful in some cases. Let's discuss the following two examples.

    What does it mean to add two altitudes? It is not meaningful. On the other hand, subtracting those should not result in an altitude, but in a quantity of height. Adding or subtracting height to/from altitude results in altitude. Subtracting altitude from height is meaningless again. Those quantities clearly model affine space. Maybe this is why ISQ defines them as one quantity type height/depth/altitude?

    What does it mean to add two position vectors? It is not meaningful again. However, subtracting those results in a displacement as we noted in the previous chapter. Adding or subtracting displacement to/from position vector results in another position vector, and subtracting position vector from displacement does not have physical sense. Again, those quantities perfectly model affine space. However, this time, those are defined as separate and independent quantities (i.e., displacement is not modeled as delta position vector or position vector is not modeled as a displacement from the origin of a coordinate system).

    Info

    Currently, mp-units does not enforce the affine space behavior for such quantities. Today, subtracting two altitudes result in an altitude and subtracting two position vectors result in a position vector. However, we plan to support automatic conversion to a proper quantity type on subtraction and addition shortly.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#non-negative-quantities","title":"Non-negative quantities","text":"

    Some quantities in the ISQ are defined as non-negative. This is a really interesting property that may be checked at runtime to increase safety. However, the number of such quantities is minimal. From a few hundred quantities provided by the ISO/IEC series, only the following have this property mentioned explicitly:

    If height was defined separately from altitude, it could probably also join this group.

    Let's think a bit more about this. What does it mean that a quantity is non-negative? Indeed, it is hard to imagine something of a negative width or radius. However, if we subtract two widths, the second one may be larger. This will result in a negative quantity of width, violating our precondition. So, is it non-negative or not?

    Again, we have to talk about the affine space abstractions. Every empirical measurement can be expressed as a point. Such points for some quantities may be non-negative indeed.

    Non-negative quantities do not end on the ones provided above. For example, speed is a good example here as well. In general, all magnitudes of vector quantities will also have this property.

    When subtracting two points, we end up with a delta/displacement type, which may be negative even for quantities listed as non-negative in the ISQ. As stated in the previous chapter, having affine space abstractions acknowledged in ISQ would greatly help here.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#lack-of-quantity-recipes","title":"Lack of quantity recipes","text":"

    Definition of many derived quantities provides their recipes in the form of quantity equations (e.g., weight equation in the previous chapter). However, some of them do not. Instead, they often provide a very generic description.

    For example, force is defined as:

    Quote

    vector (ISO 80000-2) quantity describing interaction between bodies or particles.

    This is not helpful for programming languages that like explicit definitions. Different vendors may interpret the above differently, which will result in different implementations that will not be compatible with each other.

    As the derived quantity of force has to be a vector quantity, it has to be defined in terms of at least one other vector quantity. We have a few to choose from:

    It is not stated explicitly in ISQ which one of those should be used and how.

    Info

    In mp-units we decided to define force as \\(F = m\\;a\\).

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#lack-of-generic-quantities-and-name-conflicts","title":"Lack of generic quantities and name conflicts","text":"

    In the previous chapter, we complained about some definitions needing to be more complex or generic. On the other hand, we also lack some generic quantities in ISQ that could serve as a root for a quantity hierarchy tree.

    For example:

    First, the above definitions have somehow conflicting names which makes it hard for the programming languages to name them consistently by different vendors.

    Info

    In mp-units, we chose mechanical_power and electromagnetism_power for those.

    Second, we do not have any other more generic definition of power to put above those in the tree. Not having it makes it hard to answer what should be the result of:

    quantity q = isq::mechanical_power(42 * W) + isq::electromagnetism_power(60 * W);\n

    Info

    To solve the above problem, we have added isq::power in mp-units, that has a really generic definition of:

    inline constexpr struct power : quantity_spec<mass* pow<2>(length) / pow<3>(time)> {} power;\n
    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#invalid-definitions-order","title":"Invalid definitions order","text":"

    Energy is defined a bit better than power, but still not without issues.

    The first time ISQ mentions energy is in the ISO 80000-4 \"Mechanics\". It defines potential energy, kinetic energy, and a mechanical energy as the sum of the first two. Right after that a mechanical work/work is defined.

    Then ISO 80000-5 \"Thermodynamics\" defines energy <thermodynamics> as:

    Quote

    ability of a system to do work (ISO 80000-4).

    Next, internal energy/thermodynamic energy is defined in terms of the change of heat.

    From the above, it seems that what is called energy <thermodynamics> should actually be the root of our tree and probably be provided in Part 4 before the mechanical energy is defined.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#hierarchies-of-derived-quantities","title":"Hierarchies of derived quantities","text":"

    Derived quantities of the same kind are often independently defined in the ISQ. The ISO/IEC 80000 series often does not suggest any hierarchy between those. Even more, it states:

    ISO/IEC Guide 99

    The division of \u2018quantity\u2019 according to \u2018kind of quantity\u2019 is, to some extent, arbitrary.

    Because of this, it is unknown or ambiguous how to form a hierarchy tree for such quantities.

    To get some sense of the complexity here, let's look again at our tree of quantities of a kind energy:

    flowchart TD\n    energy[\"<b>energy</b><br><i>(mass * length<sup>2</sup> / time<sup>2</sup>)</i><br>[J]\"]\n    energy --- mechanical_energy[\"<b>mechanical_energy</b>\"]\n    mechanical_energy --- potential_energy[\"<b>potential_energy</b>\"]\n    mechanical_energy --- kinetic_energy[\"<b>kinetic_energy</b>\"]\n    energy --- enthalpy[\"<b>enthalpy</b>\"]\n    enthalpy --- internal_energy[\"<b>internal_energy</b> / <b>thermodynamic_energy</b>\"]\n    internal_energy --- Helmholtz_energy[\"<b>Helmholtz_energy</b> / <b>Helmholtz_function</b>\"]\n    enthalpy --- Gibbs_energy[\"<b>Gibbs_energy</b> / <b>Gibbs_function</b>\"]\n    energy --- active_energy[\"<b>active_energy</b>\"]

    Not being exact means that every vendor may implement it differently. This will result in:

    It would be great if ISQ could provide specific division of quantities into kinds and more information about the position of each quantity within the hierarchy of quantities of the same kind.

    Important

    We can try to do this by ourselves, but it is tough. Probably no one, for sure we are not, is an expert in all the fields of ISO/IEC 80000 applicability.

    We need the help of subject matter experts who will help us build those trees for their domains and then verify that everything works as expected.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#the-same-or-a-different-kind","title":"The same or a different kind?","text":"

    Some quantities are more complicated than others. For example, power has:

    How should we model this? Maybe those should be two or three independent trees of quantities, each having its own unit?

    flowchart TD\n    power[\"<b>power</b><br><i>(mass * length<sup>2</sup> / time<sup>3</sup>)</i><br>[W]\"]\n    power --- mechanical_power[\"<b>mechanical_power</b><br><i>(scalar_product(force, velocity))</i>\"]\n    power --- electromagnetism_power[\"<b>electromagnetism_power</b> | <b>instantaneous_power</b><br><i>(instantaneous_voltage * instantaneous_electric_current)</i>\"]\n    power --- active_power[\"<b>active_power</b><br><i>(1 / period * instantaneous_power * time)<br>(re(complex_power))</i>\"]\n\n    nonactive_power[\"<b>nonactive_power</b><br><i>(mass * length<sup>2</sup> / time<sup>3</sup>)</i><br>[VA]\"]\n    nonactive_power --- reactive_power[\"<b>reactive_power</b><br><i>(im(complex_power))</i><br>[var]\"]\n\n    complex_power[\"<b>complex_power</b><br>{complex}<br><i>(voltage_phasor * electric_current_phasor)<br>(active_power + j * reactive_power)</i><br>[VA]\"]\n    complex_power --- apparent_power[\"<b>apparent_power</b><br><i>(voltage * electric_current)<br>(mod(complex_power))</i>\"]

    This will mean that we will not be able to add or compare active power, reactive power, and apparent power, which probably makes a lot of sense. However, it also means that the following will fail to compile:

    quantity apparent = isq::apparent_power(100 * VA);\nquantity active = isq::active_power(60 * W);\nquantity<isq::nonactive_power[VA]> q = sqrt(pow<2>(apparent) - pow<2>(active)); // Compile-time error\n

    Also the following will not work:

    quantity active = isq::active_power(60 * W);\nquantity reactive = isq::reactive_power(40 * var);\nquantity<isq::apparent_power[VA]> q = sqrt(pow<2>(active) + pow<2>(reactive)); // Compile-time error\n

    If we want the above to work maybe we need to implement the tree as follows?

    flowchart TD\n    power[\"<b>power</b><br><i>(mass * length<sup>2</sup> / time<sup>3</sup>)</i><br>[W]\"]\n    power --- mechanical_power[\"<b>mechanical_power</b><br><i>(scalar_product(force, velocity))</i>\"]\n    power --- electromagnetism_power[\"<b>electromagnetism_power</b> | <b>instantaneous_power</b><br><i>(instantaneous_voltage * instantaneous_electric_current)</i>\"]\n    power --- apparent_power[\"<b>apparent_power</b><br><i>(voltage * electric_current)<br>(mod(complex_power))</i><br>[VA]\"]\n    apparent_power --- active_power[\"<b>active_power</b><br><i>(1 / period * instantaneous_power * time)<br>(re(complex_power))</i>\"]\n    apparent_power --- nonactive_power[\"<b>nonactive_power</b><br><i>(sqrt(apparent_power<sup>2</sup> - active_power<sup>2</sup>))</i><br>\"]\n    nonactive_power --- reactive_power[\"<b>reactive_power</b><br><i>(im(complex_power))</i><br>[var]\"]\n    apparent_power --- complex_power[\"<b>complex_power</b><br>{complex}<br><i>(voltage_phasor * electric_current_phasor)<br>(active_power + j * reactive_power)</i>\"]

    However, the above allows direct addition and comparison of active power and nonactive power, and also will not complain if someone will try to use watt (W) as a unit of apparent power or reactive power.

    Again, ISQ does not provide a direct answer here.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#more-base-quantities","title":"More base quantities?","text":"

    Is ISQ really based on only seven base quantities? Let's look at the definition of traffic intensity in IEC 80000-13 \"Information science and technology\":

    Quote

    number of simultaneously busy resources in a particular pool of resources.

    It looks like a definition of a specialized dimensionless quantity or, more correctly, a quantity of dimension one. This would not be the only such case. Even in the same Part 13, we can find quantities like storage capacity with a similar property.

    Only when we look closer do we start to see differences. All dimensionless quantities, even if they have their own dedicated units, can also be measured in a unit of one (1). This is true for storage capacity (also measured in bits), angular measure (also measured in radians), _solid angular measure (also measured in steradians), and more.

    However, traffic intensity can only be measured in erlangs (E), not in a unit one (1). Does it mean that it is a \"hidden\" 8-th base quantity in ISQ? If so, should it have its own dimension as well?

    Angular quantities are another interesting case here. Scientists have written petitions and papers for years to make them an additional dimension in ISQ and SI. More about this can be found in our documentation's Strong Angular System chapter.

    "},{"location":"blog/2024/11/11/international-system-of-quantities-isq-part-6---challenges/#summary","title":"Summary","text":"

    ISQ is tremendous and solves many problems we had in modeling various subjects for years in software. As a result, we have more powerful tools in our hands that allow us to deliver safer products.

    Unfortunately, ISQ, contrarily to SI, is not widely recognized, and no libraries besides mp-units model it in any programming language. Keeping it behind a paywall does not help either. We hope that posts from this series will spread in the community, raise awareness of ISQ and its benefits, and encourage authors of other libraries to implement it in their products.

    Despite all the benefits, it is essential to realize that ISQ has many problems. International standards should be specified in such a way that there is no room for ambiguity in their interpretation by different parties trying to use them. As described above, this is not the case here.

    ISQ is not ready to be unambiguously modeled in software by various vendors. Here are the most important problems to solve to allow this:

    1. ISQ needs to define basic operations on quantities:

    - what the result of addition and subtraction should be when arguments differ, \u00a0 \u00a0 - convertibility rules.

    1. The exact quantity equation recipe needs to be included for many derived quantities.
    2. Many ISQ quantities do not provide their exact relation versus other quantities of the same kind (no strict hierarchy).
    3. Some missing quantities need to be included. Others would benefit from corrected names.

    Additionally:

    could improve the safety of our programs and products that people depend on with their lives on a daily basis.

    I hope you enjoyed following this series and learned more about the International System of Quantities. Please try it out in your domain and share feedback with us. We always love to hear about the projects in which our library is being used and about use cases it helps address.

    "},{"location":"blog/2023/11/12/report-from-the-kona-2023-iso-c-committee-meeting/","title":"Report from the Kona 2023 ISO C++ Committee meeting","text":"

    Several groups in the ISO C++ Committee reviewed the P1935: A C++ Approach to Physical Units proposal in Belfast 2019 and Prague 2020. All those groups expressed interest in the potential standardization of such a library and encouraged further work. The authors also got valuable initial feedback that highly influenced the design of the V2 version of the mp-units library.

    In the following years, we scoped on getting more feedback from the production and design. This resulted in version 2 of the mp-units library that resolved many issues the users and Committee members raised. The features and interfaces of this version are close to being the best we can get with the current version of the C++ language standard.

    We submitted three new proposals related to the standardization of the quantities and units library for the last ISO C++ Committee meeting:

    Those were reviewed and briefly discussed in several groups: Numerics (SG6), Safety & Security (SG23), and Library Evolution Working Group (LEWG). Most of the feedback was positive, and the Committee is interested in spending more time on such proposals.

    The following poll was taken by the LEWG:

    LEWG POLL: Given that our time is limited, more time should be promised for a quantities and units library

    Strongly in Favor In favor Neutral Against Strongly Against 10 13 4 0 0

    Attendance: 22 + 6

    Number of Authors: 4

    Authors\u2019 position: 4x SF

    Outcome: Strong consensus in favor

    Additionally, some concerns were raised about the large scope of the proposal. We were encouraged to return with more details and design rationale in a unified paper. This is what we are working on now for the next Committee meeting that will happen in mid-March 2024 in Tokyo.

    "},{"location":"blog/2024/07/02/report-from-the-st-louis-2024-iso-c-committee-meeting/","title":"Report from the St. Louis 2024 ISO C++ Committee meeting","text":"

    We made significant progress in the standardization of this library during the ISO C++ Committee meeting in St. Louis.

    "},{"location":"blog/2024/07/02/report-from-the-st-louis-2024-iso-c-committee-meeting/#p30942r3-stdbasic_fixed_string","title":"P30942R3: std::basic_fixed_string","text":"

    First, the fixed_string was unanimously forwarded from the SG18 LEWG Incubator to the Library Evolution Working Group (LEWG). The group suggested a few minor changes to the paper, which resulted in the R3 version of the proposal.

    The paper is in excellent shape, and the entire wording is ready as well. Hopefully it will progress quickly through the remaining groups in the Committee.

    "},{"location":"blog/2024/07/02/report-from-the-st-louis-2024-iso-c-committee-meeting/#p3045r1-quantities-and-units-library","title":"P3045R1: Quantities and units library","text":"

    In the SG6 (Numerics), we had a really efficient discussion about the recently raised usability issues with temperatures and the Minimal Viable Product (MVP) scope.

    The following polls were taken:

    POLL: If WG21 adds anything to the standard to provide units or quantities, then such a solution must at least include the necessary abstractions for units, dimensions, and quantity kinds. (It does not have to provide system definitions, e.g. ISQ/SI definitions.)

    Strongly in Favor In favor Neutral Against Strongly Against 7 4 7 0 0

    POLL: If WG21 adds anything to the standard to provide units or quantities, then such a solution must at least include the necessary abstractions for units, dimensions, quantity kinds, and quantities of the same kind. (It does not have to provide system definitions, e.g. ISQ/SI definitions.)

    Strongly in Favor In favor Neutral Against Strongly Against 5 2 5 2 0

    POLL: If WG21 adds anything to the standard to provide units or quantities, then such a solution must at least include the necessary abstractions for units, dimensions, quantity kinds, and affine spaces. (It does not have to provide system definitions, e.g. ISQ/SI definitions.)

    Strongly in Favor In favor Neutral Against Strongly Against 5 0 8 1 0

    As we can see, there are no controversies about the first poll that states that the MVP should include at least:

    The next polls add either:

    SG6 considered those less important, but no one was strongly against including those in the MVP. We were asked to return with better motivation and usage examples for those features.

    If you are depending on quantities of the same kind or quantity points in your project and you would like to see them in the std library, please let us know about your use cases.

    Besides SG6, we spent six hours in the SG18 LEWG Incubator discussing the details of the library design. The proposal was very well received, and we got a few valuable comments and suggestions that we will apply to the next version of the paper.

    "},{"location":"blog/2024/04/15/report-from-the-tokyo-2024-iso-c-committee-meeting/","title":"Report from the Tokyo 2024 ISO C++ Committee meeting","text":"

    The Tokyo 2024 meeting was a very important step in the standardization of this library. Several WG21 groups reviewed proposals, and the feedback was really good.

    "},{"location":"blog/2024/04/15/report-from-the-tokyo-2024-iso-c-committee-meeting/#p3045r0-quantities-and-units-library","title":"P3045R0: Quantities and units library","text":"

    The Study Group 6 (Numerics) discussed the proposal for several hours. The initial feedback was positive. There were some concerns related to the description and design of the affine space abstractions in the library. Besides that, the people in the room liked what they saw.

    We run a few polls in SG6 as well:

    POLL: The syntax number * unit is the right solution for constructing quantities. Not allowing reordering the operands is correct.

    Strongly in Favor In favor Neutral Against Strongly Against 5 4 1 0 1

    POLL: Not defining any UDLs is the right solution.

    No objection to unanimous consent.

    The paper was also briefly discussed in SG18 LEWG Incubator, and the initial feedback was also positive. No polls were taken.

    SG16 Unicode does not meet during ISO C++ Committee F2F meetings. Still, the text output chapter paper was also reviewed by it during an online meeting before Tokyo. We got good feedback and are expected to return with the updated version. No polls were taken.

    "},{"location":"blog/2024/04/15/report-from-the-tokyo-2024-iso-c-committee-meeting/#p30942r1-stdbasic_fixed_string","title":"P30942R1: std::basic_fixed_string","text":"

    In the SG18 LEWG Incubator, before we started to talk about P3045R0, we spent a few hours discussing the design of the std::basic_fixed_string, which is proposed for C++26. The group gave excellent feedback, and if the R2 version addresses it properly, the paper is expected to progress to LEWG (Library Evolution Working Group) in St. Louis.

    Plenty of polls were taken:

    POLL: We should promise more committee time to pursuing std::basic_fixed_string, knowing that our time is scarce and this will leave less time for other work.

    Strongly in Favor In favor Neutral Against Strongly Against 11 0 0 0 0

    POLL: Should the constructor from a string literal be consteval?

    Strongly in Favor In favor Neutral Against Strongly Against 6 3 2 0 0

    POLL: Do we want to add .view()?

    Strongly in Favor In favor Neutral Against Strongly Against 3 5 3 0 0

    POLL: Do we want the .size member to be an integral_constant<size_t, N> (and .empty to be bool_constant<N==0>)?

    Strongly in Favor In favor Neutral Against Strongly Against 5 2 2 2 0

    POLL: Should the index operator[] return a reference to const?

    Strongly in Favor In favor Neutral Against Strongly Against 2 2 3 3 0

    POLL: Should the constructor from a string literal have a precondition that txt[N] == 0?

    Strongly in Favor In favor Neutral Against Strongly Against 6 1 2 0 2"},{"location":"blog/2024/11/25/report-from-the-wroc%C5%82aw-2024-iso-c-committee-meeting/","title":"Report from the Wroc\u0142aw 2024 ISO C++ Committee meeting","text":"

    The Wroc\u0142aw 2024 meeting was another efficient step in the standardization of this library. We've spent the entire day on the joint LEWGI and SG6 discussion and got lots of feedback. We've also introduced std::fixed_string to LEWG for C++26.

    "},{"location":"blog/2024/11/25/report-from-the-wroc%C5%82aw-2024-iso-c-committee-meeting/#p3045r4-quantities-and-units-library","title":"P3045R4: Quantities and units library","text":"

    We have presented the following chapters of our proposal to LEWGI and SG6. We reviewed all the usage examples, discussed composing symbols for derived dimensions and units, and looked into formatting specifications for quantities. We also discussed the minimal scope of the proposal.

    We got plenty of feedback on:

    We were also asked to extend the library to provide text output support for quantity points.

    You can expect all of those changes to appear in the next release.

    "},{"location":"blog/2024/11/25/report-from-the-wroc%C5%82aw-2024-iso-c-committee-meeting/#p30942r5-stdbasic_fixed_string","title":"P30942R5: std::basic_fixed_string","text":"

    The paper was well received. However, Barry Revzin submitted P3380 paper in September. This started a discussion about the scope of this proposal. Should we:

    "},{"location":"getting_started/contributing/","title":"Contributing","text":"

    \ud83d\udc4d\ud83c\udf89 First off, thanks for taking the time to contribute! \ud83c\udf89\ud83d\udc4d

    "},{"location":"getting_started/contributing/#mp-units-documentation","title":"mp-units documentation","text":"

    Before contributing, it is highly recommended to familiarize yourself with our official documentation.

    This file is also a part of it, and this is why it has non-standard Markdown formatting (which can be seen when reading in a regular Markdown renderer). To benefit from full mkdocs rendering, please switch to the Contributing chapter of our documentation.

    "},{"location":"getting_started/contributing/#where-to-start","title":"Where to start?","text":"

    If you are looking for a good issue to start with, please check the following:

    "},{"location":"getting_started/contributing/#gitpod","title":"Gitpod","text":"

    The easiest way to start coding is to jump straight into Gitpod environment. You can either click the button below

    or prefix any mp-units URL (main branch, other branches, issues, PRs, ...) in your web browser with gitpod.io/# (e.g., https://gitpod.io/#https://github.com/mpusz/mp-units).

    The above environment provides you with:

    "},{"location":"getting_started/contributing/#building-testing-and-packaging","title":"Building, testing, and packaging","text":"

    Alternatively, please refer to our official docs for download, build, and install instructions with the below changes if you want to set up a development environment on your local machine.

    "},{"location":"getting_started/contributing/#conan-configuration-properties","title":"Conan configuration properties","text":"user.mp-units.build:all

    Enables compilation of all the source code, including tests and examples. To support this, it requires some additional Conan build dependencies described in Repository directory tree and dependencies. It also runs unit tests during the Conan build (unless tools.build:skip_test configuration property is set to True).

    user.mp-units.build:skip_la

    If user.mp-units.build:all is enabled, among others, Conan installs the external wg21-linear_algebra dependency and enables the compilation of linear algebra-based tests and usage examples. Such behavior can be disabled with this option.

    user.mp-units.analyze:clang-tidy

    Enables clang-tidy analysis.

    "},{"location":"getting_started/contributing/#cmake-options-for-mp-units-project-developers","title":"CMake options for mp-units project developers","text":"MP_UNITS_DEV_BUILD_LA

    2.2.0 \u00b7 ON/OFF (Default: ON)

    Enables building code depending on the linear algebra library.

    MP_UNITS_DEV_IWYU

    2.2.0 \u00b7 ON/OFF (Default: OFF)

    Enables include-what-you-use analysis.

    MP_UNITS_DEV_CLANG_TIDY

    2.2.0 \u00b7 ON/OFF (Default: OFF)

    Enables clang-tidy analysis.

    MP_UNITS_DEV_TIME_TRACE

    2.5.0 \u00b7 NONE/ALL/MODULES/HEADERS (Default: NONE)

    Enables compilation performance data collection with -ftime-trace for clang compilers.

    All our unit tests compile only for headers and never for modules. To allow fair comparison, MODULES and HEADERS do not enable the data collection for unit tests. This means that they affect only the core, systems, and examples.

    Please use ALL to profile unit tests as well.

    "},{"location":"getting_started/contributing/#building-the-entire-repository","title":"Building the entire repository","text":"

    To build all the mp-units source code (with unit tests and examples), you should:

    1. Use the CMakeLists.txt from the top-level directory.
    2. Run Conan with user.mp-units.build:all = True.
    git clone https://github.com/mpusz/mp-units.git && cd mp-units\nconan build . -pr <your_conan_profile> -s compiler.cppstd=23 -c user.mp-units.build:all=True -b missing\n

    The above will download and install all of the dependencies needed for the development of the library, build all of the source code, and run unit tests.

    If you prefer to build the project via CMake rather than Conan, then you should replace the conan build with conan install command and then follow with a regular CMake build and testing:

    conan install . -pr <your_conan_profile> -s compiler.cppstd=23 -c user.mp-units.build:all=True -b missing\ncmake --preset conan-default\ncmake --build --preset conan-release\ncmake --build --preset conan-release --target all_verify_interface_header_sets\ncmake --build --preset conan-release --target test\n

    Hint

    To ensure that we always build all the targets and to save some typing of the Conan commands, we can set the following in the ~/.conan2/global.conf:

    user.mp-units.build:all=True\n
    "},{"location":"getting_started/contributing/#packaging","title":"Packaging","text":"

    To test CMake installation and Conan packaging run:

    conan create . --user <username> --channel <channel> -pr <your_conan_profile> -s compiler.cppstd=23 \\\n               -c user.mp-units.build:all=True -b missing\n

    The above will create a Conan package and run tests provided in ./test_package directory.

    In case you would like to upload mp-units package to the Conan server, do the following:

    conan upload -r <remote-name> --all mp-units/2.2.0@<user>/<channel>\n
    "},{"location":"getting_started/contributing/#building-documentation","title":"Building documentation","text":"

    We are building our documentation using Material for MkDocs. The easiest way to install all the required dependencies is with pip:

    pip install -U mkdocs-material mkdocs-rss-plugin\n

    Additionally, a Cairo Graphics library is required by Material for MkDocs. Please follow the official MkDocs documentation to install it.

    After that, you can either:

    "},{"location":"getting_started/contributing/#generating-api-reference","title":"Generating API reference","text":"

    We need to take a few steps to set up our environment so that we are ready to generate API reference documents.

    First, we need to satisfy the requirements described in https://github.com/cplusplus/draft and https://github.com/Eelis/cxxdraft-htmlgen. On the Ubuntu platform, this is equivalent to the following instructions run from the user's home directory:

    sudo apt install latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended lmodern\nsudo apt install haskell-stack graphviz nodejs npm ghc cabal-install\nnpm install split mathjax-full mathjax-node-sre mathjax-node-cli\ncabal update\n

    On some platforms, installing mathjax-node-cli through npm does update the system's PATH environment variable resulting in tex2html not found errors. In such cases we need to add the .bin folder to the PATH environment variable manually:

    echo \"export PATH=\\\"~/node_modules/.bin:\\$PATH\\\"\" >> ~/.bashrc && source ~/.bashrc\n

    Next, we need to clone the following git repositories:

    For example:

    git clone https://github.com/JohelEGP/jegp.cmake_modules.git --depth=1\ngit clone https://github.com/JohelEGP/draft.git --branch=standardese_sources_base --depth=1\ngit clone https://github.com/JohelEGP/cxxdraft-htmlgen.git --branch=standardese_sources_base --depth=1\n

    Now, we are ready to start building our API reference. First, we need to configure CMake with the following:

    cmake -S docs/api_reference/src -B build/docs/api_reference \\\n      -DCMAKE_MODULE_PATH=\"<path to gh:JohelEGP/jegp.cmake_modules>/modules\" \\\n\u00a0 \u00a0 \u00a0 -DJEGP_STANDARDESE_SOURCES_GIT_REPOSITORY=\"<path to gh:JohelEGP/draft>\" \\\n      -DJEGP_CXXDRAFT_HTMLGEN_GIT_REPOSITORY=\"<path to gh:JohelEGP/cxxdraft-htmlgen>\"\n

    Then we need to build the docs with CMake:

    cmake --build build/docs/api_reference\n

    In the end, we need to move the generated documentation to the docs/api_reference/gen subdirectory:

    mv build/docs/api_reference/mp-units.html docs/api_reference/gen\n

    or just link the entire directory:

    ln -sf ../../build/docs/api_reference/mp-units.html docs/api_reference/gen\n
    "},{"location":"getting_started/contributing/#before-committing-git-changes","title":"Before committing git changes","text":"

    There are a few steps recommended to check before committing and pushing your changes to the git repository.

    "},{"location":"getting_started/contributing/#naming-conventions","title":"Naming conventions","text":"

    Here are the main rules for naming things in this repo:

    "},{"location":"getting_started/contributing/#unified-code-formatting","title":"Unified code formatting","text":"

    A formatting standard is enforced with the pre-commit script. Before committing your changes, please do the following:

    pip install -U pre-commit\npre-commit run --all-files\n

    This will run:

    The script will run on all the files in the repo and will apply the changes in place when needed. After the script is done, please make sure to review and stage all those changes for the git commit.

    "},{"location":"getting_started/contributing/#backward-compatibility","title":"Backward compatibility","text":"

    Before submission, please remember to check if the code compiles fine on the supported compilers. The CI will check it anyway, but it is good to check at least some of the configurations before pushing changes. Especially older compilers can be tricky as those do not have full C++20 conformance. The official list of supported compilers can always be found in the C++ compiler support (API/ABI) chapter of our documentation.

    "},{"location":"getting_started/cpp_compiler_support/","title":"C++ compiler support (API/ABI)","text":"

    Info

    mp-units library tries to provide the best user experience possible with the C++ language. To achieve that, it extensively uses the latest C++ language features.

    Even though the library benefits from the latest C++ versions (if available), C++20 is enough to compile and use all of the library's functionality. Newer features can be hidden behind some preprocessor macros providing a backward-compatible way to use them.

    The table below provides the minimum compiler version required to compile the code using a specific C++ feature:

    C++ Feature C++ version gcc clang apple-clang MSVC Minimum support 20 12+ 16+ && !19 15+ 194+ std::format 20 13+ 17+ 16+ 194+ C++ modules 20 None 17+ None None import std; 23 None 18+ None None Explicit this parameter 23 14+ 18+ None None clang-19 unfixable bug

    Unfortunately, clang-19 does not build mp-units because of an unfixable bug in the compiler.

    MSVC bugs

    MSVC still has a poor C++20 conformance. We had to make many workarounds to our codebase to make it compile on this compiler. Usage of such nasty preprocessor macros degrade the readability and maintainability of our code. This is why we've applied those patches to the main library code but not to unit tests and examples. Those still do not compile on MSVC.

    Here is a list of the most important MSVC bugs:

    Please upvote them so they get a higher fixing priority at Microsoft.

    Important

    Enabling/disabling features listed above may influence the API of the library and the ABI of the customers' projects.

    "},{"location":"getting_started/cpp_compiler_support/#stdformat","title":"std::format","text":""},{"location":"getting_started/cpp_compiler_support/#c-modules","title":"C++ modules","text":"

    Note

    More requirements for C++ modules support can be found in the CMake's documentation.

    "},{"location":"getting_started/cpp_compiler_support/#import-std","title":"import std;","text":""},{"location":"getting_started/cpp_compiler_support/#explicit-this-parameter","title":"Explicit this parameter","text":""},{"location":"getting_started/faq/","title":"Frequently Asked Questions","text":""},{"location":"getting_started/faq/#why-do-we-spell-metre-instead-of-meter","title":"Why do we spell metre instead of meter?","text":"

    This is how the BIPM defines it in the SI Brochure (British English spelling by default).

    "},{"location":"getting_started/faq/#why-dont-we-use-udls-to-create-quantities","title":"Why don't we use UDLs to create quantities?","text":"

    Many reasons make UDLs a poor choice for a physical units library:

    1. UDLs work only with literals (compile-time known values). Our observation is that besides the unit tests, there are only a few compile-time known quantity values used in the production code. Please note that for physical constants, we recommend using Faster-than-lightspeed Constants.

    2. Typical implementations of UDLs tend to always use the widest representation type available. In the case of std::chrono::duration, the following is true:

      using namespace std::chrono_literals;\nauto d1 = 42s;\nauto d2 = 42.s;\nstatic_assert(std::is_same_v<decltype(d1)::rep, std::int64_t>);\nstatic_assert(std::is_same_v<decltype(d2)::rep, long double>);\n

    When such UDL is intermixed in arithmetics with any quantity type of a shorter representation type, it will always expand it to the longest one. In other words, such long type spreads until all types use it everywhere.

    1. While increasing the coverage for the library, we learned that many unit symbols conflict with built-in types or numeric extensions. A few of those are: F (farad), J (joule), W (watt), K (kelvin), d (day), l or L (litre), erg, ergps. Usage of the _ prefix would make it work for mp-units, but in case the library is standardized, those naming collisions would be a big issue. This is why we came up with the _q_ prefix that would become q_ after standardization (e.g., 42q_s), which is not that nice anymore.

    2. UDLs with the same identifiers defined in different namespace can't be disambiguated in the C++ language. If both SI and CGS systems define _q_s UDL for a second unit, then it would not be possible to specify which one to use in case both namespaces are \"imported\" with using directives.

    3. Another bad property of UDLs is that they do not compose. A coherent unit of angular momentum would have a UDL specified as _q_kg_m2_per_s. Now imagine that we want to make every possible user happy. How many variations of that unit would we predefine for differently scaled versions of all unit ingredients?

    4. UDLs are also really expensive to define and specify. Typically, for each unit, we need two definitions. One for integral and another one for floating-point representation. Before the V2 framework, the coherent unit of angular momentum was defined as:

      constexpr auto operator\"\" _q_kg_m2_per_s(unsigned long long l)\n{\n  gsl_Expects(std::in_range<std::int64_t>(l));\n  return angular_momentum<kilogram_metre_sq_per_second, std::int64_t>(static_cast<std::int64_t>(l));\n}\n\nconstexpr auto operator\"\" _q_kg_m2_per_s(long double l)\n{\n  return angular_momentum<kilogram_metre_sq_per_second, long double>(l);\n}\n
    "},{"location":"getting_started/faq/#why-cant-i-create-a-quantity-by-passing-a-number-to-a-constructor","title":"Why can't I create a quantity by passing a number to a constructor?","text":"

    A quantity class template in the mp-units library has no publicly available constructor taking a raw value. Such support is provided by the std::chrono::duration and was pointed out to us as a red flag safety issue by a few parties already.

    Consider the following structure and a code using it:

    struct X {\n  std::vector<std::chrono::milliseconds> vec;\n  // ...\n};\n
    X x;\nx.vec.emplace_back(42);\n

    Everything works fine for years until, at some point, someone changes the structure to:

    struct X {\n  std::vector<std::chrono::microseconds> vec;\n  // ...\n};\n

    The code continues to compile just fine, but all the calculations are off now. This is why we decided to not follow this path.

    In the mp-units library, both a number and a unit have to always be explicitly provided in order to form a quantity.

    Note

    The same applies to the construction of quantity_point using an explicit point origin. To prevent similar safety issues during maintenance, the initialization always requires providing both a quantity and a PointOrigin that we use as a reference point.

    "},{"location":"getting_started/faq/#why-a-dimensionless-quantity-is-not-just-a-fundamental-arithmetic-type","title":"Why a dimensionless quantity is not just a fundamental arithmetic type?","text":"

    In the initial design of this library, the resulting type of division of two quantities was their common representation type:

    static_assert(std::is_same_v<decltype(10 * km / (5 * km)), int>);\n

    First of all, this was consistent with std::chrono::duration behavior. Additional reasoning behind it was not providing a false impression of a strong quantity type for something that looks and feels like a regular number. Also, all of the mathematic and trigonometric functions were working fine out of the box with such representation types, so we did not have to rewrite sin(), cos(), exp(), and others.

    However, the feedback we got from the production usage was that such an approach is really bad for generic programming. It is hard to handle the result of the two quantities' division (or multiplication) as it might be either a quantity or a fundamental type. If we want to raise such a result to some power, we must use units::pow or std::pow depending on the resulting type. Those are only a few issues related to such an approach.

    Moreover, suppose we divide quantities of the same dimension but with units of significantly different magnitudes. In that case, we may end up with a really small or a huge floating-point value, which may result in losing lots of precision. Returning a dimensionless quantity from such cases allows us to benefit from all the properties of scaled units and is consistent with the rest of the library.

    Note

    More information on the current design can be found in the Dimensionless Quantities chapter.

    "},{"location":"getting_started/faq/#why-derived-units-order-is-not-preserved-from-the-multiplication","title":"Why derived units order is not preserved from the multiplication?","text":"

    It might be surprising, but the quantities and units multiplication order does not impact the order of components in the derived unit. Let's try the following example:

    std::println(\"{}\", 42 * kW * h);\nconstexpr auto kWh = kW * h;\nstd::println(\"{}\", 42 * kWh);\n

    The above prints:

    42 h kW\n42 h kW\n

    Some users could expect to see 42 kWh or 42 kW h in the output. It is not the case and for a very good reason. As stated in Simplifying the resulting symbolic expressions, to be able to reason about and simplify units, the library needs to order them in an appropriate order.

    Maybe this default order could be improved a bit, but according to international standards, there is no generic ordering rule. Various quantities use different, often domain-specific, ordering of derived unit components.

    Let's see what SI says here:

    Derived quantity Symbol Derived unit expressed in terms of base units electric field strength V m\u207b\u00b9 kg m s\u207b\u00b3 A\u207b\u00b9 electric charge density C m\u207b\u00b3 A s m\u207b\u00b3 exposure (x- and \u03b3-rays) C kg\u207b\u00b9 A s kg\u207b\u00b9

    However, there is a workaround. A user can define its own named unit for a derived unit and provide the custom symbol text that suits the project's requirements. For example, the above case could be addressed with:

    inline constexpr struct kilowatt_hour final : named_unit<\"kWh\", kW * h> {} kilowatt_hour;\ninline constexpr auto kWh = kilowatt_hour;\n

    With the above, we can refactor the above code to:

    std::println(\"{}\", 42 * kWh);\nstd::println(\"{}\", (42 * kW * h).in(kWh));\n

    Both lines will produce an expected \"42 kWh\" unit in the output.

    Important

    Please note that this makes the entire \"kWh\" a single, indivisible entity that is not subject to simplification rules. This means that 42 * kWh / (2 * h) will result with 21 kWh/h rather than 21 kW. To get the latter, the user needs to explicitly provide a new derived unit:

    std::println(\"{}\", (42 * kWh / (2 * h)).in(kW));\n
    "},{"location":"getting_started/faq/#why-do-the-identifiers-for-concepts-in-the-library-use-camelcase","title":"Why do the identifiers for concepts in the library use CamelCase?","text":"

    Initially, C++20 was meant to use CamelCase for all the concept identifiers. All the concepts from the std::ranges library were merged with such names into the standard document draft. Frustratingly, CamelCase concepts got dropped from the C++ standard at the last moment before releasing C++20. Now, we are facing the predictable consequences of running out of names.

    As long as some concepts in the library could be easily named with a standard_case there are some that are hard to distinguish from the corresponding type names, such as Quantity, QuantityPoint, QuantitySpec, or Reference. This is why we decided to use CamelCase consistently for all the concept identifiers to make it clear when we are talking about a type or concept identifier.

    However, we are aware that this might be a temporary solution. In case the library gets standardized, we can expect the ISO C++ Committee to bikeshed/rename all of the concept identifiers to a standard_case, even if it will result in a harder to understand code.

    Note

    In case you have a good idea of how to rename existing concepts to the standard_case, please let us know in the associated GitHub Issue.

    "},{"location":"getting_started/faq/#why-utf-8-quantity-symbols-are-used-by-default-instead-of-portable-characters","title":"Why UTF-8 quantity symbols are used by default instead of portable characters?","text":"

    Both C++ and ISO 80000 are standardized by the ISO. ISO 80000 and the SI standards specify UTF-8 symbols as the official unit names for some quantities (e.g. \u03a9 symbol for the resistance quantity). As the mp-units library will be proposed for standardization as a part of the C++ Standard Library we have to obey the rules and be consistent with ISO specifications.

    Note

    We do understand engineering reality and the constraints of some environments. This is why the library has the option of Portable Quantity Symbols.

    "},{"location":"getting_started/faq/#why-dont-we-have-cmake-options-to-disable-the-building-of-tests-and-examples","title":"Why don't we have CMake options to disable the building of tests and examples?","text":"

    Over time, many people provided PRs proposing adding options to build tests and examples conditionally. Here are a few examples:

    We admit this is a common practice in the industry, but we also believe this is a bad pattern.

    First, the only need for such options comes when a user wants to use add_subdirectory() in CMake to handle dependencies. Such an approach does not scale and should be discouraged. There is little use for such a practice in times when we have dedicated package managers like Conan.

    The second thing is that our observation is that many people are fixed on disabling \"unneeded\" subdirectories from compilation, but they do not see or address the biggest issue, which is polluting user's build environment with our development-specific settings. Propagating our restrictive compilation flags to user's project is not the best idea as it might cause a lot of harm if this project stops to compile because of that.

    Last but not least, not having those options is on purpose. Top level CMakeLists.txt file should only be used by mp-units developers and contributors as an entry point for the project's development. We want to ensure that everyone will build ALL the code correctly before pushing a commit. Having such options would allow unintended issues to leak to PRs and CI.

    This is why our projects have two entry points:

    Note

    For more details on this please refer to the CMake + Conan: 3 Years Later - Mateusz Pusz lecture that Mateusz Pusz provided at the C++Now 2021 conference.

    "},{"location":"getting_started/installation_and_usage/","title":"Installation And Usage","text":"

    This chapter provides all the necessary information to obtain mp-units and build the user's source code using it.

    "},{"location":"getting_started/installation_and_usage/#obtaining-dependencies","title":"Obtaining dependencies","text":"

    This library assumes that most of the dependencies will be provided by the Conan Package Manager. If you want to obtain required dependencies by other means, some modifications to the library's CMake files might be needed.

    Conan quick intro

    In case you are not familiar with Conan, to install it (or upgrade) just do:

    pip install -U conan\n

    After that, you might need to add a custom profile file for your development environment in ~/.conan2/profiles directory. An example profile can look as follows:

    ~/.conan2/profiles/gcc12
    [settings]\narch=x86_64\nbuild_type=Release\ncompiler=gcc\ncompiler.cppstd=20\ncompiler.libcxx=libstdc++11\ncompiler.version=14\nos=Linux\n\n[conf]\ntools.build:compiler_executables={\"c\": \"gcc-14\", \"cpp\": \"g++-14\"}\n

    Setting the language version

    Please note that the mp-units library requires at least C++20 to be set in a Conan profile or forced via the Conan command line. If we do the former, we will not need to provide -s compiler.cppstd=20 every time we run a Conan command line (as provided in the command line instructions below).

    Using Ninja as a CMake generator for Conan

    It is highly recommended to set Ninja as a CMake generator for Conan. To do so, we could create a ~/.conan2/global.conf file that will set tools.cmake.cmaketoolchain:generator to one of the Ninja generators. For example:

    ~/.conan2/global.conf
    tools.cmake.cmaketoolchain:generator=\"Ninja Multi-Config\"\n

    Separate build folders for different configurations

    ~/.conan2/global.conf file may also set tools.cmake.cmake_layout:build_folder_vars which makes working with several compilers or build configurations easier. For example, the below line will force Conan to generate separate CMake presets and folders for each compiler and C++ standard version:

    ~/.conan2/global.conf
    tools.cmake.cmake_layout:build_folder_vars=[\"settings.compiler\", \"settings.compiler.version\", \"settings.compiler.cppstd\"]\n

    In such a case, we will need to use a configuration-specific preset name in the Conan instructions provided below rather than just conan-default and conan-release (e.g., conan-gcc-13-23 and conan-gcc-13-23-release)

    CMake with presets support

    It is recommended to use at least CMake 3.23 to build this project to benefit from CMake Presets generated by Conan. All build instructions below assume that you have such support. If not, your CMake invocations have to be replaced with something like:

    mkdir build && cd build\ncmake .. -G \"Ninja Multi-Config\" -DCMAKE_TOOLCHAIN_FILE=<path_to_generators_dir>/conan_toolchain.cmake\ncmake --build . --config Release\n

    Tip

    In case you can't use CMake 3.23 but you have access to CMake 3.20 or later, you can append -c tools.cmake.cmaketoolchain.presets:max_schema_version=2 to the conan install command which will force Conan to use an older version of the CMake Presets schema.

    "},{"location":"getting_started/installation_and_usage/#build-options","title":"Build options","text":"

    Note

    Most of the below options are related to the C++ language features available in the compilers. Please refer to the C++ compiler support chapter to learn more about which C++ features are required for each option and which compilers support them.

    "},{"location":"getting_started/installation_and_usage/#conan-options","title":"Conan options","text":"cxx_modules

    2.2.0 \u00b7 True/False (Default: automatically determined from settings)

    Configures CMake to add C++ modules to the list of default targets.

    import_std

    2.3.0 \u00b7 True/False (Default: automatically determined from settings)

    Enables import std; usage.

    std_format

    2.2.0 \u00b7 True/False (Default: automatically determined from settings)

    Enables the usage of std::format and associated facilities for text formatting. If it is not supported, then the {fmt} library is used instead.

    no_crtp

    2.2.0 \u00b7 True/False (Default: automatically determined from settings)

    Removes the need for the usage of the CRTP idiom in the quantity_spec definitions.

    contracts

    2.2.0 \u00b7 none/gsl-lite/ms-gsl (Default: see below)

    Enables checking of preconditions and additional assertions in the code.

    If the automatically determined default for import_std is True, then the contracts option is set to none by default. gsl-lite otherwise.

    freestanding

    2.2.0 \u00b7 True/False (Default: False)

    Configures the library in the freestanding mode. When enabled, the library's source code will build with the compiler's -ffreestanding compilation option without any issues.

    CMake options to set when Conan is not being used"},{"location":"getting_started/installation_and_usage/#cmake-options","title":"CMake options","text":"

    Conan will automatically set all the below CMake options based on its configuration (described above). Manual setting of the below CMake options is only needed when Conan is not being used.

    MP_UNITS_BUILD_AS_SYSTEM_HEADERS

    2.2.0 \u00b7 ON/OFF (Default: OFF)

    Exports library as system headers.

    MP_UNITS_BUILD_CXX_MODULES

    2.2.0 \u00b7 ON/OFF (Default: OFF)

    Adds C++ modules to the list of default targets.

    MP_UNITS_API_STD_FORMAT

    2.2.0 \u00b7 ON/OFF (Default: automatically determined)

    Enables the usage of std::format and associated facilities for text formatting. If it is not supported, then the {fmt} library is used instead.

    MP_UNITS_API_NO_CRTP

    2.2.0 \u00b7 ON/OFF (Default: automatically determined)

    Removes the need for the usage of the CRTP idiom in the quantity_spec definitions.

    MP_UNITS_API_CONTRACTS

    2.2.0 \u00b7 NONE/GSL-LITE/MS-GSL (Default: GSL-LITE)

    Enables checking of preconditions and additional asserts in the code.

    MP_UNITS_API_FREESTANDING

    2.2.0 \u00b7 ON/OFF (Default: OFF)

    Configures the library in the freestanding mode. When enabled, the library's source code should build with the compiler's -ffreestanding compilation option without any issues.

    "},{"location":"getting_started/installation_and_usage/#installation-and-reuse","title":"Installation and reuse","text":"

    There are many different ways of installing/reusing mp-units in your project. Below we mention only a few of many options possible.

    Important: Prefer using Conan if possible

    The easiest and most recommended way to obtain mp-units is with the Conan package manager. See Conan + CMake (release) for a detailed instruction.

    "},{"location":"getting_started/installation_and_usage/#conan-cmake-release","title":"Conan + CMake (release)","text":"

    Tip

    If you are new to the Conan package manager you may want to read Obtaining Dependencies and refer to the Consuming packages chapter of the official Conan documentation for more information.

    mp-units releases are hosted on Conan-Center. The following steps may be performed to obtain an official library release:

    1. Create Conan configuration file (either conanfile.txt or conanfile.py) in your project's top-level directory and add mp-units as a dependency of your project. For example, the simplest file may look as follows:

      conanfile.txtconanfile.py 
      [requires]\nmp-units/2.4.0\n\n[options]\n# The below mp-units options are set to defaults by Conan.\n# Uncomment and set to an explicit value to override the defaults.\n#\n# mp-units*:cxx_modules=True\n# mp-units*:import_std=False\n# mp-units*:std_format=True\n# mp-units*:no_crtp=True\n# mp-units*:contracts=gsl-lite\n# mp-units*:freestanding=False\n\n[layout]\ncmake_layout\n\n[generators]\nCMakeToolchain\nCMakeDeps\n
      from conan import ConanFile\nfrom conan.tools.build import can_run\nfrom conan.tools.cmake import CMake, cmake_layout\n\nclass MPUnitsTestConan(ConanFile):\n    settings = \"os\", \"arch\", \"compiler\", \"build_type\"\n    generators = \"CMakeDeps\", \"CMakeToolchain\"\n\n    def requirements(self):\n        self.requires(\n            \"mp-units/2.4.0\",\n            options={\n                # The below mp-units options are set to defaults by Conan.\n                # Uncomment and set to an explicit value to override the defaults.\n                #\n                # \"cxx_modules\": False,\n                # \"import_std\": False,\n                # \"std_format\": True,\n                # \"no_crtp\": True,\n                # \"contracts\": \"gsl-lite\",\n                # \"freestanding\": False,\n            },\n        )\n\n    def layout(self):\n        cmake_layout(self)\n\n    def build(self):\n        cmake = CMake(self)\n        cmake.configure()\n        cmake.build()\n        if can_run(self):\n            cmake.ctest(cli_args=[\"--output-on-failure\"])\n

    2. Import mp-units and its dependencies definitions with find_package:

      find_package(mp-units REQUIRED)\n

    3. Link your CMake targets with mp-units:

      target_link_libraries(<your_target> <PUBLIC|PRIVATE|INTERFACE> mp-units::mp-units)\n

    4. Download, build, and install Conan dependencies before running the CMake configuration step:

      conanfile.txt or conanfile.pyconanfile.py only 
      conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing\ncmake --preset conan-default\ncmake --build --preset conan-release\ncmake --build --preset conan-release --target test\n
      conan build . -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing\n
    "},{"location":"getting_started/installation_and_usage/#conan-cmake-live-at-head","title":"Conan + CMake (Live At Head)","text":"

    This chapter describes the procedure to Live At Head, which means using the latest stable version of mp-units all the time.

    Note

    Please note that even though the Conan packages that you will be using are generated ONLY for builds that are considered stable (passed our CI tests), some minor regressions may happen (CI and C++ build environments are not perfect yet). Also, please expect that the library interface might, and probably will, change occasionally. Even though we do our best, such changes might not be reflected in the project's documentation right away.

    The procedure is similar to the one described in Conan + CMake (release) with the following differences:

    1. Before starting the previous procedure, add mp-units remote to your Conan configuration:

      conan remote add conan-mpusz https://mpusz.jfrog.io/artifactory/api/conan/conan-oss\n

    2. In your Conan configuration file, provide the package identifier of the mpusz/testing stream:

      conanfile.txtconanfile.py 
      [requires]\nmp-units/2.5.0@mpusz/testing\n\n[options]\n# The below mp-units options are set to defaults by Conan.\n# Uncomment and set to an explicit value to override the defaults.\n#\n# mp-units*:cxx_modules=True\n# mp-units*:import_std=False\n# mp-units*:std_format=True\n# mp-units*:no_crtp=True\n# mp-units*:contracts=gsl-lite\n# mp-units*:freestanding=False\n\n[layout]\ncmake_layout\n\n[generators]\nCMakeToolchain\nCMakeDeps\n
      from conan import ConanFile\nfrom conan.tools.build import can_run\nfrom conan.tools.cmake import CMake, cmake_layout\n\nclass MPUnitsTestConan(ConanFile):\n    settings = \"os\", \"arch\", \"compiler\", \"build_type\"\n    generators = \"CMakeDeps\", \"CMakeToolchain\"\n\n    def requirements(self):\n        self.requires(\n            \"mp-units/2.5.0@mpusz/testing\",\n            options={\n                # The below mp-units options are set to defaults by Conan.\n                # Uncomment and set to an explicit value to override the defaults.\n                #\n                # \"cxx_modules\": False,\n                # \"import_std\": False,\n                # \"std_format\": True,\n                # \"no_crtp\": True,\n                # \"contracts\": \"gsl-lite\",\n                # \"freestanding\": False,\n            },\n        )\n\n    def layout(self):\n        cmake_layout(self)\n\n    def build(self):\n        cmake = CMake(self)\n        cmake.configure()\n        cmake.build()\n        if can_run(self):\n            cmake.ctest(cli_args=[\"--output-on-failure\"])\n

      Tip

      The identifiers of the latest packages can always be found in the project's README file or on the project's Artifactory.

    3. Force Conan to check for updated recipes with -u:

      conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing -u\n
    Alternative installation scenarios"},{"location":"getting_started/installation_and_usage/#copy","title":"Copy","text":"

    As mp-units is a C++ header-only library you can simply copy all needed src/*/include subdirectories to your source tree.

    Note

    In such a case, you are on your own to ensure all the dependencies are installed and their header files can be located during the build. Please also note that some compiler-specific flags are needed to make the code compile without issues.

    "},{"location":"getting_started/installation_and_usage/#copy-cmake","title":"Copy + CMake","text":"

    If you copy the mp-units library source code from the project's ./src directory (not the entire repo from its root), you can reuse CMake targets defined by the library. To do so, you should use CMakeLists.txt file from the ./src directory:

    add_subdirectory(<path_to_mp_units_lib_folder>)\n# ...\ntarget_link_libraries(<your_target> <PUBLIC|PRIVATE|INTERFACE> mp-units::mp-units)\n

    Note

    You are still on your own to make sure all the dependencies are installed and their header and CMake configuration files can be located during the build.

    Important: Library users should not use the top-level CMake file

    Top level CMakeLists.txt file should only be used by mp-units developers and contributors as an entry point for the project's development. ./src/CMakeLists.txt contains only a pure library definition and should be used by the customers that prefer to use CMake's add_subdirectory() to handle the dependencies.

    To learn more about the rationale, please check our FAQ.

    "},{"location":"getting_started/installation_and_usage/#install","title":"Install","text":"

    If you don't want to use Conan in your project and just want to install the mp-units library on your file system, and use find_package(mp-units) from another repository to find it; it is enough to perform the following steps:

    conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing\nmv CMakeUserPresets.json src\ncd src\ncmake --preset conan-default -DCMAKE_INSTALL_PREFIX=<your_installation_path>\ncmake --build --preset conan-release --target install\n
    "},{"location":"getting_started/introduction/","title":"Introduction","text":"

    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 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 version 2.0 of mp-units were provided in detail by Mateusz Pusz in the \"The Power of C++ Templates With mp-units: Lessons Learned & a New Library Design\" talk at the C++ on Sea 2023 conference.

    "},{"location":"getting_started/introduction/#open-source","title":"Open Source","text":"

    mp-units is Free and Open Source, with a permissive MIT license. 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.

    "},{"location":"getting_started/introduction/#with-the-users-experience-in-mind","title":"With the User's Experience in Mind","text":"

    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 does 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:

    Important: It is all about errors

    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 that won't compile with a huge error log. Physical quantities and units libraries are different. Generation of compile-time errors is the main reason to use such a library.

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

    Here is a small example of operations possible on scalar quantities:

    C++ modulesHeader files 
    import mp_units;\n\nusing namespace mp_units;\nusing namespace mp_units::si::unit_symbols;\n\n// simple numeric operations\nstatic_assert(10 * km / 2 == 5 * km);\n\n// conversions to common units\nstatic_assert(1 * h == 3600 * s);\nstatic_assert(1 * km + 1 * m == 1001 * m);\n\n// derived quantities\nstatic_assert(1 * km / (1 * s) == 1000 * m / s);\nstatic_assert(2 * km / h * (2 * h) == 4 * km);\nstatic_assert(2 * km / (2 * km / h) == 1 * h);\n\nstatic_assert(2 * m * (3 * m) == 6 * m2);\n\nstatic_assert(10 * km / (5 * km) == 2);\n\nstatic_assert(1000 / (1 * s) == 1 * kHz);\n
    #include <mp-units/systems/si.h>\n\nusing namespace mp_units;\nusing namespace mp_units::si::unit_symbols;\n\n// simple numeric operations\nstatic_assert(10 * km / 2 == 5 * km);\n\n// conversions to common units\nstatic_assert(1 * h == 3600 * s);\nstatic_assert(1 * km + 1 * m == 1001 * m);\n\n// derived quantities\nstatic_assert(1 * km / (1 * s) == 1000 * m / s);\nstatic_assert(2 * km / h * (2 * h) == 4 * km);\nstatic_assert(2 * km / (2 * km / h) == 1 * h);\n\nstatic_assert(2 * m * (3 * m) == 6 * m2);\n\nstatic_assert(10 * km / (5 * km) == 2);\n\nstatic_assert(1000 / (1 * s) == 1 * kHz);\n

    Try it on Compiler Explorer

    This library requires some C++20 features (concepts and constraints, classes as NTTP, ...). Thanks to them, a user gets a powerful but still easy-to-use interface where all unit conversions and dimensional analysis can be performed without sacrificing accuracy. Please see the below example for a quick preview of basic library features:

    C++ modulesHeader files 
    #include <format>\n#include <iomanip>\n#include <iostream>\n#include <print>\nimport mp_units;\n\nusing namespace mp_units;\n\nconstexpr QuantityOf<isq::speed> auto avg_speed(QuantityOf<isq::length> auto d,\n                                                QuantityOf<isq::time> auto t)\n{\n  return d / t;\n}\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n  using namespace mp_units::international::unit_symbols;\n\n  constexpr quantity v1 = 110 * km / h;\n  constexpr quantity v2 = 70 * mph;\n  constexpr quantity v3 = avg_speed(220. * isq::distance[km], 2 * h);\n  constexpr quantity v4 = avg_speed(isq::distance(140. * mi), 2 * h);\n  constexpr quantity v5 = v3.in(m / s);\n  constexpr quantity v6 = value_cast<m / s>(v4);\n  constexpr quantity v7 = value_cast<int>(v6);\n\n  std::cout << v1 << '\\n';                                        // 110 km/h\n  std::cout << std::setw(10) << std::setfill('*') << v2 << '\\n';  // ***70 mi/h\n  std::cout << std::format(\"{:*^10}\\n\", v3);                      // *110 km/h*\n  std::println(\"{:%N in %U of %D}\", v4);                          // 70 in mi/h of LT\u207b\u00b9\n  std::println(\"{::N[.2f]}\", v5);                                 // 30.56 m/s\n  std::println(\"{::N[.2f]U[dn]}\", v6);                            // 31.29 m\u22c5s\u207b\u00b9\n  std::println(\"{:%N}\", v7);                                      // 31\n}\n
    #include <mp-units/systems/international.h>\n#include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n#include <format>\n#include <iomanip>\n#include <iostream>\n#include <print>\n\nusing namespace mp_units;\n\nconstexpr QuantityOf<isq::speed> auto avg_speed(QuantityOf<isq::length> auto d,\n                                                QuantityOf<isq::time> auto t)\n{\n  return d / t;\n}\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n  using namespace mp_units::international::unit_symbols;\n\n  constexpr quantity v1 = 110 * km / h;\n  constexpr quantity v2 = 70 * mph;\n  constexpr quantity v3 = avg_speed(220. * isq::distance[km], 2 * h);\n  constexpr quantity v4 = avg_speed(isq::distance(140. * mi), 2 * h);\n  constexpr quantity v5 = v3.in(m / s);\n  constexpr quantity v6 = value_cast<m / s>(v4);\n  constexpr quantity v7 = value_cast<int>(v6);\n\n  std::cout << v1 << '\\n';                                        // 110 km/h\n  std::cout << std::setw(10) << std::setfill('*') << v2 << '\\n';  // ***70 mi/h\n  std::cout << std::format(\"{:*^10}\\n\", v3);                      // *110 km/h*\n  std::println(\"{:%N in %U of %D}\", v4);                          // 70 in mi/h of LT\u207b\u00b9\n  std::println(\"{::N[.2f]}\", v5);                                 // 30.56 m/s\n  std::println(\"{::N[.2f]U[dn]}\", v6);                            // 31.29 m\u22c5s\u207b\u00b9\n  std::println(\"{:%N}\", v7);                                      // 31\n}\n

    Try it on Compiler Explorer

    Note

    More code examples can be found in the Examples chapter.

    "},{"location":"getting_started/project_structure/","title":"Project structure","text":"

    This chapter provides a high level overview of the project to make it easier to navigate, build, and use.

    "},{"location":"getting_started/project_structure/#cmake-projects-and-dependencies","title":"CMake projects and dependencies","text":"

    The GitHub repository contains three independent CMake-based projects:

    Important: Library users should not use the top-level CMake file

    Top level CMakeLists.txt file should only be used by mp-units developers and contributors as an entry point for the project's development. We want to ensure that everyone will build ALL the code correctly before pushing a commit. Having such options would allow unintended issues to leak to PRs and CI.

    This is why our projects have two entry points:

    To learn more about the rationale, please check our FAQ.

    "},{"location":"getting_started/project_structure/#modules","title":"Modules","text":"

    The mp-units library provides the following C++ modules:

    flowchart TD\n    mp_units --- mp_units.systems --- mp_units.core
    C++ Module CMake Target Contents mp_units.core mp-units::core Core library framework and systems-independent utilities mp_units.systems mp-units::systems All the systems of quantities and units mp_units mp-units::mp-units Core + Systems

    Note

    C++ modules are provided within the package only when:

    "},{"location":"getting_started/project_structure/#header-files","title":"Header files","text":"

    All of the project's header files can be found in the mp-units/... subdirectory.

    "},{"location":"getting_started/project_structure/#core-library","title":"Core library","text":" More details

    More detailed header files can be found in subfolders which typically should not be included by the end users:

    "},{"location":"getting_started/project_structure/#systems-and-associated-utilities","title":"Systems and associated utilities","text":"

    The systems definitions can be found in the mp-units/systems/... subdirectory:

    "},{"location":"getting_started/project_structure/#systems-of-quantities","title":"Systems of quantities","text":" Tip: Improving compile times

    mp-units/systems/isq.h might be expensive to compile in every translation unit. There are some smaller, domain targeted files available for explicit inclusion in the mp-units/systems/isq/... subdirectory.

    "},{"location":"getting_started/project_structure/#systems-of-units","title":"Systems of units","text":" Tip: Improving compile times

    mp-units/systems/si.h might be expensive to compile in every translation unit. There are some smaller files available for explicit inclusion in the mp-units/systems/si/... subdirectory.

    mp-units/systems/si/unit_symbols.h is the most expensive to include.

    "},{"location":"getting_started/quick_start/","title":"Quick Start","text":"

    This chapter provides a quick introduction to get you started with mp-units. Much more details can be found in our User's Guide.

    "},{"location":"getting_started/quick_start/#quantities","title":"Quantities","text":"

    A quantity is a concrete amount of a unit representing a quantity type of a specified dimension with a specific representation. It is represented in the library with a quantity class template.

    The SI Brochure says:

    SI Brochure

    The value of the quantity is the product of the number and the unit. The space between the number and the unit is regarded as a multiplication sign (just as a space between units implies multiplication).

    Following the above, the value of a quantity in the mp-units library is created by multiplying a number with a predefined unit:

    C++ modulesHeader files 
    import mp_units;\n\nusing namespace mp_units;\n\nquantity q = 42 * si::metre / si::second;\n
    #include <mp-units/systems/si.h>\n\nusing namespace mp_units;\n\nquantity q = 42 * si::metre / si::second;\n

    Info

    In case someone doesn't like the multiply syntax or there is an ambiguity between operator* provided by this and other libraries, there are two other ways to create a quantity:

    1. delta construction helper:

      C++ modulesHeader files 
      import mp_units;\n\nusing namespace mp_units;\n\nquantity q = delta<si::metre / si::second>(42);\n
      #include <mp-units/systems/si.h>\n\nusing namespace mp_units;\n\nquantity q = delta<si::metre / si::second>(42);\n

    2. A two-parameter constructor:

      C++ modulesHeader files 
      import mp_units;\n\nusing namespace mp_units;\n\nquantity q{42, si::metre / si::second};\n
      #include <mp-units/systems/si.h>\n\nusing namespace mp_units;\n\nquantity q{42, si::metre / si::second};\n

    The above creates an instance of quantity<derived_unit<si::metre, per<si::second>>{}, int>. The same can be obtained using optional unit symbols:

    C++ modulesHeader files 
    import mp_units;\n\nusing namespace mp_units;\nusing namespace mp_units::si::unit_symbols;\n\nquantity q = 42 * m / s;\n
    #include <mp-units/systems/si.h>\n\nusing namespace mp_units;\nusing namespace mp_units::si::unit_symbols;\n\nquantity q = 42 * m / s;\n

    Important

    Unit symbols introduce a lot of short identifiers into the current scope, which may cause naming collisions with unrelated but already existing identifiers in the code base. This is why unit symbols are opt-in and typically should be imported only in the context where they are being used (e.g., function scope).

    A user has several options here to choose from depending on the required scenario and possible naming conflicts:

    using-directiveusing-declarationcustom short identifierunit names

    Explicitly \"import\" all of the symbols of a specific system of units from a dedicated unit_symbols namespace with a using-directive:

    using namespace mp_units;\n\nvoid foo(double speed_m_s)\n{\n  // imports all the SI symbols at once\n  using namespace si::unit_symbols;\n  quantity speed = speed_m_s * m / s;\n  // ...\n}\n

    Note

    This solution is perfect for small and isolated scopes but can cause surprising issues when used in larger scopes or when used for the entire program namespace.

    There are 29 named units in SI, and each of them has many prefixed variations (e.g., ng, kcd, ...). It is pretty easy to introduce a name collision with those.

    Selectively bring only the required and not-conflicting symbols with using-declarations:

    using namespace mp_units;\n\nvoid foo(double N)\n{\n  // 'N' function parameter would collide with the SI symbol for Newton, so we only bring what we need\n  using si::unit_symbols::m;\n  using si::unit_symbols::s;\n  quantity speed = N * m / s;\n  // ...\n}\n

    Specify a custom not conflicting unit identifier for a unit:

    using namespace mp_units;\n\nvoid foo(double speed_m_s)\n{\n  // names of some local variables are conflicting with the symbols we want to use\n  auto m = ...;\n  auto s = ...;\n\n  constexpr Unit auto mps = si::metre / si::second;\n  quantity speed = speed_m_s * mps;\n}\n

    Full unit names are straightforward to use and often provide the most readable code:

    using namespace mp_units;\n\nvoid foo(double m, double s)\n{\n  quantity speed = m * si::metre / (s * si::second);\n  // ...\n}\n

    Quantities of the same kind can be added, subtracted, and compared to each other:

    C++ modulesHeader files 
    import mp_units;\n\nusing namespace mp_units;\nusing namespace mp_units::si::unit_symbols;\n\nstatic_assert(1 * km + 50 * m == 1050 * m);\n
    #include <mp-units/systems/si.h>\n\nusing namespace mp_units;\nusing namespace mp_units::si::unit_symbols;\n\nstatic_assert(1 * km + 50 * m == 1050 * m);\n

    Various quantities can be multiplied or divided by each other:

    static_assert(140 * km / (2 * h) == 70 * km / h);\n

    Note

    In case you wonder why this library does not use UDLs to create quantities, please check our FAQ.

    "},{"location":"getting_started/quick_start/#quantity-points","title":"Quantity points","text":"

    The quantity point specifies an absolute quantity with respect to an origin. If no origin is provided explicitly, an implicit one will be provided by the library.

    Together with quantities, they model The Affine Space.

    Quantity points should be used in all places where adding two values is meaningless (e.g., temperature points, timestamps, altitudes, readouts from the car's odometer, etc.).

    The set of operations that can be done on quantity points is limited compared to quantities. This introduces an additional type-safety.

    C++ modulesHeader files 
    #include <print>\nimport mp_units;\n\nint main()\n{\n  using namespace mp_units;\n  using namespace mp_units::si::unit_symbols;\n  using namespace mp_units::usc::unit_symbols;\n\n  quantity_point temp = point<deg_C>(20.);\n  std::println(\"Temperature: {} ({})\",\n               temp.quantity_from_zero(),\n               temp.in(deg_F).quantity_from_zero());\n}\n
    #include <mp-units/systems/si.h>\n#include <mp-units/systems/usc.h>\n#include <print>\n\nint main()\n{\n  using namespace mp_units;\n  using namespace mp_units::si::unit_symbols;\n  using namespace mp_units::usc::unit_symbols;\n\n  quantity_point temp = point<deg_C>(20.);\n  std::println(\"Temperature: {} ({})\",\n               temp.quantity_from_zero(),\n               temp.in(deg_F).quantity_from_zero());\n}\n

    The above outputs:

    Temperature: 20 \u2103 (68 \u2109)\n

    Info

    Check The Affine Space chapter to learn more about quantity points.

    "},{"location":"users_guide/terms_and_definitions/","title":"Terms and Definitions","text":"

    The mp-units project consistently uses the official metrology vocabulary defined by the ISO and BIPM. You can find essential project-related definitions in our documentation's \"Glossary\" chapter. Even more, terms are provided in the official metrology vocabulary of the ISO and BIPM.

    Tip

    Please familiarize yourself with terms from \"Glossary\" to better understand the documentation and improve domain-related communication and discussions.

    "},{"location":"users_guide/examples/avg_speed/","title":"avg_speed","text":"

    Try it on Compiler Explorer

    Let's continue the previous example. This time, our purpose will not be to showcase as many library features as possible, but we will scope on different interfaces one can provide with the mp-units. We will also describe some advantages and disadvantages of presented solutions.

    First, we either import a module or include all the necessary header files and import all the identifiers from the mp_units namespace:

    avg_speed.cpp
    #ifdef MP_UNITS_IMPORT_STD\nimport std;\n#else\n#include <exception>\n#include <iostream>\n#endif\n#ifdef MP_UNITS_MODULES\nimport mp_units;\n#else\n#include <mp-units/systems/cgs.h>\n#include <mp-units/systems/international.h>\n#include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n#endif\n\nnamespace {\n\nusing namespace mp_units;\n

    Next, we define two functions calculating average speed based on quantities of fixed units and integral and floating-point representation types, respectively, and a third function that we introduced in the previous example:

    avg_speed.cpp
    constexpr quantity<si::metre / si::second, int> fixed_int_si_avg_speed(quantity<si::metre, int> d,\n                                                                       quantity<si::second, int> t)\n{\n  return d / t;\n}\n\nconstexpr quantity<si::metre / si::second> fixed_double_si_avg_speed(quantity<si::metre> d, quantity<si::second> t)\n{\n  return d / t;\n}\n\nconstexpr QuantityOf<isq::speed> auto avg_speed(QuantityOf<isq::length> auto d, QuantityOf<isq::time> auto t)\n{\n  return d / t;\n}\n

    We also added a simple utility to print our results:

    avg_speed.cpp
    template<QuantityOf<isq::length> D, QuantityOf<isq::time> T, QuantityOf<isq::speed> V>\nvoid print_result(D distance, T duration, V speed)\n{\n  const auto result_in_kmph = speed.force_in(si::kilo<si::metre> / non_si::hour);\n  std::cout << \"Average speed of a car that makes \" << distance << \" in \" << duration << \" is \" << result_in_kmph\n            << \".\\n\";\n}\n

    Now, let's analyze how those three utility functions behave with different sets of arguments. First, we are going to use quantities of SI units and integral representation:

    avg_speed.cpp
    void example()\n{\n  using namespace mp_units::si::unit_symbols;\n\n  // SI (int)\n  {\n    constexpr auto distance = 220 * km;\n    constexpr auto duration = 2 * h;\n\n    std::cout << \"SI units with 'int' as representation\\n\";\n\n    print_result(distance, duration, fixed_int_si_avg_speed(distance, duration));\n    print_result(distance, duration, fixed_double_si_avg_speed(distance, duration));\n    print_result(distance, duration, avg_speed(distance, duration));\n  }\n

    The above provides the following output:

    SI units with 'int' as representation\nAverage speed of a car that makes 220 km in 2 h is 108 km/h.\nAverage speed of a car that makes 220 km in 2 h is 110 km/h.\nAverage speed of a car that makes 220 km in 2 h is 110 km/h.\n

    Please note that in the first two cases, we must convert length from km to m and time from h to s. The converted values are used to calculate speed in m/s which is then again converted to the one in km/h. Those conversions not only impact the application's runtime performance but may also affect the precision of the final result. Such truncation can be easily observed in the first case where we deal with integral representation types (the resulting speed is 108 km/h).

    The second scenario is really similar to the previous one, but this time, function arguments have floating-point representation types:

    avg_speed.cpp
      // SI (double)\n  {\n    constexpr auto distance = 220. * km;\n    constexpr auto duration = 2. * h;\n\n    std::cout << \"\\nSI units with 'double' as representation\\n\";\n\n    // conversion from a floating-point to an integral type is a truncating one so an explicit cast is needed\n    print_result(distance, duration, fixed_int_si_avg_speed(value_cast<int>(distance), value_cast<int>(duration)));\n    print_result(distance, duration, fixed_double_si_avg_speed(distance, duration));\n    print_result(distance, duration, avg_speed(distance, duration));\n  }\n

    Conversion from floating-point to integral representation types is considered value-truncating and that is why now, in the first case, we need an explicit call to value_cast<int>.

    In the text output, we can observe that, again, the resulting value gets truncated during conversions in the first cast:

    SI units with 'double' as representation\nAverage speed of a car that makes 220 km in 2 h is 108 km/h.\nAverage speed of a car that makes 220 km in 2 h is 110 km/h.\nAverage speed of a car that makes 220 km in 2 h is 110 km/h.\n

    Next, let's do the same for integral and floating-point representations, but this time using international mile:

    avg_speed.cpp
      // International mile (int)\n  {\n    using namespace mp_units::international::unit_symbols;\n\n    constexpr auto distance = 140 * mi;\n    constexpr auto duration = 2 * h;\n\n    std::cout << \"\\nInternational mile with 'int' as representation\\n\";\n\n    // it is not possible to make a lossless conversion of miles to meters on an integral type\n    // (explicit cast needed)\n    print_result(distance, duration, fixed_int_si_avg_speed(distance.force_in(m), duration));\n    print_result(distance, duration, fixed_double_si_avg_speed(distance, duration));\n    print_result(distance, duration, avg_speed(distance, duration));\n  }\n\n  // International mile (double)\n  {\n    using namespace mp_units::international::unit_symbols;\n\n    constexpr auto distance = 140. * mi;\n    constexpr auto duration = 2. * h;\n\n    std::cout << \"\\nInternational mile with 'double' as representation\\n\";\n\n    // conversion from a floating-point to an integral type is a truncating one so an explicit cast is needed\n    // also it is not possible to make a lossless conversion of miles to meters on an integral type\n    // (explicit cast needed)\n    print_result(distance, duration, fixed_int_si_avg_speed(value_cast<m, int>(distance), value_cast<int>(duration)));\n    print_result(distance, duration, fixed_double_si_avg_speed(distance, duration));\n    print_result(distance, duration, avg_speed(distance, duration));\n  }\n

    One important difference here is the fact that as it is not possible to make a lossless conversion of miles to meters on a quantity using an integral representation type, so this time, we need a value_cast<m, int> to force it.

    If we check the text output of the above, we will see the following:

    International mile with 'int' as representation\nAverage speed of a car that makes 140 mi in 2 h is 111 km/h.\nAverage speed of a car that makes 140 mi in 2 h is 112.654 km/h.\nAverage speed of a car that makes 140 mi in 2 h is 112 km/h.\n\nInternational mile with 'double' as representation\nAverage speed of a car that makes 140 mi in 2 h is 111 km/h.\nAverage speed of a car that makes 140 mi in 2 h is 112.654 km/h.\nAverage speed of a car that makes 140 mi in 2 h is 112.654 km/h.\n

    Please note how the first and third results get truncated using integral representation types.

    In the end, we repeat the scenario for CGS units:

    avg_speed.cpp
      // CGS (int)\n  {\n    constexpr auto distance = 22'000'000 * cgs::centimetre;\n    constexpr auto duration = 7200 * cgs::second;\n\n    std::cout << \"\\nCGS units with 'int' as representation\\n\";\n\n    // it is not possible to make a lossless conversion of centimeters to meters on an integral type\n    // (explicit cast needed)\n    print_result(distance, duration, fixed_int_si_avg_speed(distance.force_in(m), duration));\n    print_result(distance, duration, fixed_double_si_avg_speed(distance, duration));\n    print_result(distance, duration, avg_speed(distance, duration));\n  }\n\n  // CGS (double)\n  {\n    constexpr auto distance = 22'000'000. * cgs::centimetre;\n    constexpr auto duration = 7200. * cgs::second;\n\n    std::cout << \"\\nCGS units with 'double' as representation\\n\";\n\n    // conversion from a floating-point to an integral type is a truncating one so an explicit cast is needed\n    // it is not possible to make a lossless conversion of centimeters to meters on an integral type\n    // (explicit cast needed)\n    print_result(distance, duration, fixed_int_si_avg_speed(value_cast<m, int>(distance), value_cast<int>(duration)));\n\n    print_result(distance, duration, fixed_double_si_avg_speed(distance, duration));\n    print_result(distance, duration, avg_speed(distance, duration));\n  }\n}\n\n}  // namespace\n

    Again, we observe value_cast being used in the same places and consistent truncation errors in the text output:

    CGS units with 'int' as representation\nAverage speed of a car that makes 22000000 cm in 7200 s is 108 km/h.\nAverage speed of a car that makes 22000000 cm in 7200 s is 110 km/h.\nAverage speed of a car that makes 22000000 cm in 7200 s is 109 km/h.\n\nCGS units with 'double' as representation\nAverage speed of a car that makes 2.2e+07 cm in 7200 s is 108 km/h.\nAverage speed of a car that makes 2.2e+07 cm in 7200 s is 110 km/h.\nAverage speed of a car that makes 2.2e+07 cm in 7200 s is 110 km/h.\n

    The example file ends with a simple main() function:

    avg_speed.cpp
    int main()\n{\n  try {\n    example();\n  } catch (const std::exception& ex) {\n    std::cerr << \"Unhandled std exception caught: \" << ex.what() << '\\n';\n  } catch (...) {\n    std::cerr << \"Unhandled unknown exception caught\\n\";\n  }\n}\n
    ","tags":["CGS System","International System"]},{"location":"users_guide/examples/hello_units/","title":"hello_units","text":"

    Try it on Compiler Explorer

    This is a really simple example showcasing the features of the mp-units library.

    First, we either import the mp_units module or include the headers for:

    hello_units.cpp
    #include <mp-units/compat_macros.h>\n#include <mp-units/ext/format.h>\n#ifdef MP_UNITS_IMPORT_STD\nimport std;\n#else\n#include <iomanip>\n#include <iostream>\n#endif\n#ifdef MP_UNITS_MODULES\nimport mp_units;\n#else\n#include <mp-units/systems/international.h>\n#include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n#endif\n

    Also, to shorten the definitions, we \"import\" all the symbols from the mp_units namespace.

    hello_units.cpp
    using namespace mp_units;\n

    Next, we define a simple function that calculates the average speed based on the provided arguments of length and time:

    hello_units.cpp
    constexpr QuantityOf<isq::speed> auto avg_speed(QuantityOf<isq::length> auto d, QuantityOf<isq::time> auto t)\n{\n  return d / t;\n}\n

    The above function template takes any quantities implicitly convertible to isq::length and isq::time, respectively. Those quantities can use any compatible unit and a representation type. The function returns a result of a straightforward equation and ensures that its quantity type is implicitly convertible to isq::speed.

    Tip

    Besides verifying the type returned from the function, constraining a generic return type is beneficial for users of such a function as it provides more information of what to expect from a function than just using auto.

    hello_units.cpp
    int main()\n{\n  using namespace mp_units::si::unit_symbols;\n  using namespace mp_units::international::unit_symbols;\n

    The above lines explicitly opt into using unit symbols from two systems of units. As this introduces a lot of short identifiers into the current scope, it is not done implicitly while including a header file.

    hello_units.cpp
      constexpr quantity v1 = 110 * km / h;\n  constexpr quantity v2 = 70 * mph;\n  constexpr quantity v3 = avg_speed(220. * km, 2 * h);\n  constexpr quantity v4 = avg_speed(isq::distance(140. * mi), 2 * isq::duration[h]);\n  constexpr quantity v5 = v3.in(m / s);\n  constexpr quantity v6 = value_cast<m / s>(v4);\n  constexpr quantity v7 = value_cast<int>(v6);\n
    hello_units.cpp
      std::cout << v1 << '\\n';                                           // 110 km/h\n  std::cout << std::setw(10) << std::setfill('*') << v2 << '\\n';     // ***70 mi/h\n  std::cout << MP_UNITS_STD_FMT::format(\"{:*^10}\\n\", v3);            // *110 km/h*\n  std::cout << MP_UNITS_STD_FMT::format(\"{:%N in %U of %D}\\n\", v4);  // 70 in mi/h of LT\u207b\u00b9\n  std::cout << MP_UNITS_STD_FMT::format(\"{::N[.2f]}\\n\", v5);         // 30.56 m/s\n  std::cout << MP_UNITS_STD_FMT::format(\"{::N[.2f]U[dn]}\\n\", v6);    // 31.29 m\u22c5s\u207b\u00b9\n  std::cout << MP_UNITS_STD_FMT::format(\"{:%N}\\n\", v7);              // 31\n}\n

    The above presents various ways to print a quantity. Both stream insertion operations and std::format facilities are supported.

    Tip

    MP_UNITS_STD_FMT is used for compatibility reasons. If a specific compiler does not support std::format or a user prefers to use the {fmt} library, this macro will resolve to fmt namespace. Otherwise, the std namespace will be used.

    More about it can be found in the Wide Compatibility chapter.

    ","tags":["International System","Text Formatting"]},{"location":"users_guide/examples/hw_voltage/","title":"hw_voltage","text":"

    Try it on Compiler Explorer

    As it was stated in The Affine Space chapter, every measurement can (and probably should) be modelled as a quantity_point. This is a perfect example of such a use case.

    This example implements a simplified scenario of measuring voltage read from hardware through a mapped 16-bits register. The actual voltage range of [-10 V, 10 V] is mapped to [-32767, 32767] on hardware. Translation of the value requires not only scaling of the value but also applying of an offset.

    First we include all the dependencies:

    hw_voltage.cpp
    #include <mp-units/compat_macros.h>\n#include <mp-units/ext/format.h>\n#ifdef MP_UNITS_IMPORT_STD\nimport std;\n#else\n#include <iostream>\n#include <optional>\n#endif\n#ifdef MP_UNITS_MODULES\nimport mp_units;\n#else\n#include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n#endif\n\nusing namespace mp_units;\n

    Next, we specify the real measurement voltage range to be in the range of [-10, 10]:

    hw_voltage.cpp
    // real voltage range\ninline constexpr int min_voltage = -10;\ninline constexpr int max_voltage = 10;\ninline constexpr int voltage_range = max_voltage - min_voltage;\n

    and provide a storage type and special values for the hardware representation:

    hw_voltage.cpp
    // hardware encoding of voltage\nusing voltage_hw_t = std::uint16_t;\ninline constexpr voltage_hw_t voltage_hw_error = std::numeric_limits<voltage_hw_t>::max();\ninline constexpr voltage_hw_t voltage_hw_min = 0;\ninline constexpr voltage_hw_t voltage_hw_max = voltage_hw_error - 1;\ninline constexpr voltage_hw_t voltage_hw_range = voltage_hw_max - voltage_hw_min;\ninline constexpr voltage_hw_t voltage_hw_zero = voltage_hw_range / 2;\n

    Finally, we define a quantity point origin, an offset unit that scales the value and uses this origin to offset the zero of the sale, and a dedicated quantity point alias using those:

    hw_voltage.cpp
    inline constexpr struct hw_voltage_origin final :\n  relative_point_origin<point<si::volt>(min_voltage)> {} hw_voltage_origin;\n\ninline constexpr struct hw_voltage_unit final :\n  named_unit<\"hwV\", mag_ratio<voltage_range, voltage_hw_range> * si::volt, hw_voltage_origin> {} hw_voltage_unit;\n\nusing hw_voltage_quantity_point = quantity_point<hw_voltage_unit, hw_voltage_origin, voltage_hw_t>;\n

    Now, when everything is ready, we can simulate mapping of our hardware register, and provide a helper function that will read the value and construct a quantity point from the obtained copy:

    hw_voltage.cpp
    // mapped HW register\nvolatile voltage_hw_t hw_voltage_value;\n\nstd::optional<hw_voltage_quantity_point> read_hw_voltage()\n{\n  voltage_hw_t local_copy = hw_voltage_value;\n  if (local_copy == voltage_hw_error) return std::nullopt;\n  return point<hw_voltage_unit>(local_copy);\n}\n

    We also provide a simple print helper for our quantity points:

    hw_voltage.cpp
    void print(QuantityPoint auto qp)\n{\n  std::cout << MP_UNITS_STD_FMT::format(\"{:10} ({:5})\", qp.quantity_from_zero(),\n                                        value_cast<double, si::volt>(qp).quantity_from_zero());\n}\n

    In the main function we simulate setting of 3 values by our hardware. Each of them is read and printed in the voltage unit used on the hardware as well as in the standard SI unit:

    hw_voltage.cpp
    int main()\n{\n  // simulate reading of 3 values from the hardware\n  hw_voltage_value = voltage_hw_min;\n  quantity_point qp1 = read_hw_voltage().value();\n  hw_voltage_value = voltage_hw_zero;\n  quantity_point qp2 = read_hw_voltage().value();\n  hw_voltage_value = voltage_hw_max;\n  quantity_point qp3 = read_hw_voltage().value();\n\n  print(qp1);\n  print(qp2);\n  print(qp3);\n}\n

    The above program results with the following text output:

         0 hwV (-10 V)\n 32767 hwV (  0 V)\n 65534 hwV ( 10 V)\n
    ","tags":["Affine Space","Embedded","Text Formatting"]},{"location":"users_guide/examples/si_constants/","title":"si_constants","text":"

    Try it on Compiler Explorer

    The next example presents all the seven defining constants of the SI system. We can observe how Faster-than-lightspeed Constants work in practice.

    si_constants.cpp
    #include <mp-units/compat_macros.h>\n#include <mp-units/ext/format.h>\n#ifdef MP_UNITS_IMPORT_STD\nimport std;\n#else\n#include <iostream>\n#endif\n#ifdef MP_UNITS_MODULES\nimport mp_units;\n#else\n#include <mp-units/systems/si.h>\n#endif\n

    As always, we start with the inclusion of all the needed header files. The main part of the example prints all of the SI-defining constants:

    si_constants.cpp
    int main()\n{\n  using namespace mp_units;\n  using namespace mp_units::si;\n  using namespace mp_units::si::unit_symbols;\n\n  std::cout << \"The seven defining constants of the SI and the seven corresponding units they define:\\n\";\n  std::cout << MP_UNITS_STD_FMT::format(\"- hyperfine transition frequency of Cs: {} = {::N[.0]}\\n\",\n                                        1. * si2019::hyperfine_structure_transition_frequency_of_cs,\n                                        (1. * si2019::hyperfine_structure_transition_frequency_of_cs).in(Hz));\n  std::cout << MP_UNITS_STD_FMT::format(\"- speed of light in vacuum:             {} = {::N[.0]}\\n\",\n                                        1. * si2019::speed_of_light_in_vacuum,\n                                        (1. * si2019::speed_of_light_in_vacuum).in(m / s));\n  std::cout << MP_UNITS_STD_FMT::format(\"- Planck constant:                      {} = {::N[.8e]}\\n\",\n                                        1. * si2019::planck_constant, (1. * si2019::planck_constant).in(J * s));\n  std::cout << MP_UNITS_STD_FMT::format(\"- elementary charge:                    {} = {::N[.9e]}\\n\",\n                                        1. * si2019::elementary_charge, (1. * si2019::elementary_charge).in(C));\n  std::cout << MP_UNITS_STD_FMT::format(\"- Boltzmann constant:                   {} = {::N[.6e]}\\n\",\n                                        1. * si2019::boltzmann_constant, (1. * si2019::boltzmann_constant).in(J / K));\n  std::cout << MP_UNITS_STD_FMT::format(\"- Avogadro constant:                    {} = {::N[.8e]}\\n\",\n                                        1. * si2019::avogadro_constant, (1. * si2019::avogadro_constant).in(one / mol));\n  std::cout << MP_UNITS_STD_FMT::format(\"- luminous efficacy:                    {} = {}\\n\",\n                                        1. * si2019::luminous_efficacy, (1. * si2019::luminous_efficacy).in(lm / W));\n}\n

    While analyzing the output of this program (provided below), we can easily notice that a direct printing of the quantity provides just a value 1 with a proper constant symbol. This is the main power of the Faster-than-lightspeed Constants feature. Only after we explicitly convert the unit of a quantity to proper SI units we get an actual numeric value of the constant.

    The seven defining constants of the SI and the seven corresponding units they define:\n- hyperfine transition frequency of Cs: 1 \u0394\u03bd_Cs = 9192631770 Hz\n- speed of light in vacuum:             1 c = 299792458 m/s\n- Planck constant:                      1 h = 6.62607015e-34 J s\n- elementary charge:                    1 e = 1.602176634e-19 C\n- Boltzmann constant:                   1 k = 1.380649e-23 J/K\n- Avogadro constant:                    1 N_A = 6.02214076e+23 1/mol\n- luminous efficacy:                    1 K_cd = 683 lm/W\n
    ","tags":["Physical Constants","Text Formatting"]},{"location":"users_guide/examples/tags_index/","title":"Tags Index","text":"

    Note

    mp-units usage example applications are meant to be built on all of the supported compilers. This is why they benefit from the Wide Compatibility mode.

    Tip

    All usage examples in this chapter are categorized with appropriate tags to simplify navigation and search of relevant code. You can either read all the examples one-by-one in the order provided by the documentation authors or, thanks to the tagging system, jump straight to the example that is the most interesting for you.

    "},{"location":"users_guide/examples/tags_index/#tag:affine-space","title":"Affine Space","text":""},{"location":"users_guide/examples/tags_index/#tag:cgs-system","title":"CGS System","text":""},{"location":"users_guide/examples/tags_index/#tag:embedded","title":"Embedded","text":""},{"location":"users_guide/examples/tags_index/#tag:international-system","title":"International System","text":""},{"location":"users_guide/examples/tags_index/#tag:physical-constants","title":"Physical Constants","text":""},{"location":"users_guide/examples/tags_index/#tag:text-formatting","title":"Text Formatting","text":""},{"location":"users_guide/framework_basics/character_of_a_quantity/","title":"Character of a Quantity","text":"

    Warning

    This chapter's features are experimental and subject to change or removal. Please share your feedback if something seems wrong or could be improved.

    "},{"location":"users_guide/framework_basics/character_of_a_quantity/#scalars-vectors-and-tensors","title":"Scalars, vectors, and tensors","text":"

    ISO 80000-2

    Scalars, vectors and tensors are mathematical objects that can be used to denote certain physical quantities and their values. They are as such independent of the particular choice of a coordinate system, whereas each scalar component of a vector or a tensor and each component vector and component tensor depend on that choice.

    Such distinction is important because each quantity character represents different properties and allows different operations to be done on its quantities.

    For example, imagine a physical units library that allows the creation of a \\(speed\\) quantity from both \\(length / time\\) and \\(length * time\\). It wouldn't be too safe to use such a product, right?

    Now we have to realize that both of the above operations (multiplication and division) are not even mathematically defined for linear algebra types such as vectors or tensors. On the other hand, two vectors can be passed as arguments to dot and cross-product operations. The result of the first one is a scalar. The second one results in a vector that is perpendicular to both vectors passed as arguments. Again, it wouldn't be safe to allow replacing those two operations with each other or expect the same results from both cases. This simply can't work.

    "},{"location":"users_guide/framework_basics/character_of_a_quantity/#isq-defines-quantities-of-all-characters","title":"ISQ defines quantities of all characters","text":"

    While defining quantities ISO 80000 explicitly mentions when a specific quantity has a vector or tensor character. Here are some examples:

    Quantity Character Quantity Equation \\(duration\\) scalar {base quantity} \\(mass\\) scalar {base quantity} \\(length\\) scalar {base quantity} \\(path\\; length\\) scalar {base quantity} \\(radius\\) scalar {base quantity} \\(position\\; vector\\) vector {base quantity} \\(velocity\\) vector \\(position\\; vector / duration\\) \\(acceleration\\) vector \\(velocity / duration\\) \\(force\\) vector \\(mass * acceleration\\) \\(power\\) scalar \\(force \\cdot velocity\\) \\(moment\\; of\\; force\\) vector \\(position\\; vector \\times force\\) \\(torque\\) scalar \\(moment\\; of\\; force \\cdot \\{unit\\; vector\\}\\) \\(surface\\; tension\\) scalar \\(\\lvert force \\rvert / length\\) \\(angular\\; displacement\\) scalar \\(path\\; length / radius\\) \\(angular\\; velocity\\) vector \\(angular\\; displacement / duration * \\{unit\\; vector\\}\\) \\(momentum\\) vector \\(mass * velocity\\) \\(angular\\; momentum\\) vector \\(position\\; vector \\times momentum\\) \\(moment\\; of\\; inertia\\) tensor \\(angular\\; momentum \\otimes angular\\; velocity\\)

    In the above equations:

    Note

    As of now, all of the C++ physical units libraries on the market besides mp-units do not support the operations mentioned above. They expose only multiplication and division operators, which do not work for linear algebra-based representation types. If a user of those libraries would like to create the quantities provided in the above table properly, this would result in a compile-time error stating that multiplication and division of two linear algebra vectors is impossible.

    "},{"location":"users_guide/framework_basics/character_of_a_quantity/#characters-dont-apply-to-dimensions-and-units","title":"Characters don't apply to dimensions and units","text":"

    ISO 80000 explicitly states that dimensions are orthogonal to quantity characters:

    ISO 80000-1:2009

    In deriving the dimension of a quantity, no account is taken of its scalar, vector, or tensor character.

    Also, it explicitly states that:

    ISO 80000-2

    All units are scalars.

    "},{"location":"users_guide/framework_basics/character_of_a_quantity/#defining-vector-and-tensor-quantities","title":"Defining vector and tensor quantities","text":"

    To specify that a specific quantity has a vector or tensor character a value of quantity_character enumeration can be appended to the quantity_spec describing such a quantity type:

    C++23C++20Portable 
    inline constexpr struct displacement final : quantity_spec<length, quantity_character::vector> {} displacement;\ninline constexpr struct position_vector final : quantity_spec<displacement> {} position_vector;\n
    inline constexpr struct displacement final : quantity_spec<displacement, length, quantity_character::vector> {} displacement;\ninline constexpr struct position_vector final : quantity_spec<position_vector, displacement> {} position_vector;\n
    QUANTITY_SPEC(displacement, length, quantity_character::vector);\nQUANTITY_SPEC(position_vector, displacement);\n

    With the above, all the quantities derived from position_vector or displacement will have a correct character determined according to the kind of operations included in the quantity equation defining a derived quantity.

    For example, velocity in the below definition will be defined as a vector quantity (no explicit character override is needed):

    C++23C++20Portable 
    inline constexpr struct velocity final : quantity_spec<speed, displacement / duration> {} velocity;\n
    inline constexpr struct velocity final : quantity_spec<velocity, speed, displacement / duration> {} velocity;\n
    QUANTITY_SPEC(velocity, speed, displacement / duration);\n
    "},{"location":"users_guide/framework_basics/character_of_a_quantity/#representation-types-for-vector-and-tensor-quantities","title":"Representation types for vector and tensor quantities","text":"

    As we remember, the quantity class template is defined as follows:

    template<Reference auto R,\n         RepresentationOf<get_quantity_spec(R)> Rep = double>\nclass quantity;\n

    The second template parameter is constrained with a RepresentationOf concept that checks if the provided representation type satisfies the requirements for the character associated with this quantity type.

    Note

    The current version of the C++ Standard Library does not provide any types that could be used as a representation type for vector and tensor quantities. This is why users are on their own here .

    To provide examples and implement unit tests, our library uses the types proposed in the P1385 and available as a Conan package in the Conan Center. However, thanks to the provided customization points, any linear algebra library types can be used as a vector or tensor quantity representation type.

    For example, here is how it can be done for the P1385 types:

    #include <matrix>\n\nusing la_vector = STD_LA::fixed_size_column_vector<double, 3>;\n\nQuantity auto q = la_vector{1, 2, 3} * isq::velocity[m / s];\n

    In case there is an ambiguity of operator* between mp-units and a linear algebra library, we can either:

    Note

    The following does not work:

    Quantity auto q1 = la_vector{1, 2, 3} * m / s;\nQuantity auto q2 = isq::velocity(la_vector{1, 2, 3} * m / s);\nquantity<isq::velocity[m/s]> q3{la_vector{1, 2, 3} * m / s};\n

    In all the cases above, the SI unit m / s has an associated scalar quantity of isq::length / isq::time. la_vector is not a correct representation type for a scalar quantity so the construction fails.

    "},{"location":"users_guide/framework_basics/concepts/","title":"Concepts","text":"

    This chapter enumerates all the user-facing concepts in the mp-units library.

    "},{"location":"users_guide/framework_basics/concepts/#Dimension","title":"Dimension<T>","text":"

    Dimension concept matches a dimension of either a base or derived quantity:

    All of the above dimensions have to be marked as final.

    "},{"location":"users_guide/framework_basics/concepts/#DimensionOf","title":"DimensionOf<T, V>","text":"

    DimensionOf concept is satisfied when both arguments satisfy a Dimension concept and when they compare equal.

    "},{"location":"users_guide/framework_basics/concepts/#QuantitySpec","title":"QuantitySpec<T>","text":"

    QuantitySpec concept matches all the quantity specifications including:

    All of the above quantity specifications have to be marked as final.

    "},{"location":"users_guide/framework_basics/concepts/#QuantitySpecOf","title":"QuantitySpecOf<T, V>","text":"

    QuantitySpecOf concept is satisfied when both arguments satisfy a QuantitySpec concept and when T is implicitly convertible to V.

    "},{"location":"users_guide/framework_basics/concepts/#UnitMagnitude","title":"UnitMagnitude<T>","text":"

    UnitMagnitude concept is satisfied by all types defining a unit magnitude.

    Info

    Unit magnitude implementation is a private implementation detail of the library.

    "},{"location":"users_guide/framework_basics/concepts/#Unit","title":"Unit<T>","text":"

    Unit concept matches all the units in the library including:

    All of the above units have to be marked as final.

    Note

    In the mp-units library, physical constants are also implemented as units.

    "},{"location":"users_guide/framework_basics/concepts/#AssociatedUnit","title":"AssociatedUnit<T>","text":"

    AssociatedUnit concept describes a unit with an associated quantity and is satisfied by:

    Examples

    All units in the SI have associated quantities. For example, si::second is specified to measure isq::time.

    Natural units typically do not have an associated quantity. For example, if we assume c = 1, a natural::second unit can be used to measure both time and length. In such case, speed would have a unit of one.

    "},{"location":"users_guide/framework_basics/concepts/#PrefixableUnit","title":"PrefixableUnit<T>","text":"

    PrefixableUnit concept is satisfied by all units derived from a named_unit class template. Such units can be passed as an argument to a prefixed_unit class template.

    "},{"location":"users_guide/framework_basics/concepts/#UnitOf","title":"UnitOf<T, V>","text":"

    UnitOf concept is satisfied for all units T for which an associated quantity spec is implicitly convertible to the provided QuantitySpec value.

    "},{"location":"users_guide/framework_basics/concepts/#Reference","title":"Reference<T>","text":"

    Reference concept is satisfied by all quantity reference types. Such types provide all the meta-information required to create a Quantity. A Reference can either be:

    "},{"location":"users_guide/framework_basics/concepts/#ReferenceOf","title":"ReferenceOf<T, V>","text":"

    ReferenceOf concept is satisfied by references T which have a quantity specification that satisfies QuantitySpecOf<V> concept.

    "},{"location":"users_guide/framework_basics/concepts/#RepresentationOf","title":"RepresentationOf<T, V>","text":"

    RepresentationOf concept constraints a type of a number that stores the value of a quantity and is satisfied:

    "},{"location":"users_guide/framework_basics/concepts/#Quantity","title":"Quantity<T>","text":"

    Quantity concept matches every quantity in the library and is satisfied by all types being or deriving from an instantiation of a quantity class template.

    "},{"location":"users_guide/framework_basics/concepts/#QuantityOf","title":"QuantityOf<T, V>","text":"

    QuantityOf concept is satisfied by all the quantities for which a ReferenceOf<V> is true.

    "},{"location":"users_guide/framework_basics/concepts/#QuantityLike","title":"QuantityLike<T>","text":"

    QuantityLike concept provides interoperability with other libraries and is satisfied by a type T for which an instantiation of quantity_like_traits type trait yields a valid type that provides:

    Examples

    This is how support for std::chrono::seconds can be provided:

    template<>\nstruct mp_units::quantity_like_traits<std::chrono::seconds> {\n  static constexpr auto reference = si::second;\n  static constexpr bool explicit_import = false;\n  static constexpr bool explicit_export = false;\n  using rep = std::chrono::seconds::rep;\n\n  [[nodiscard]] static constexpr rep to_numerical_value(const std::chrono::seconds& d)\n  {\n    return d.count();\n  }\n\n  [[nodiscard]] static constexpr std::chrono::seconds from_numerical_value(const rep& v)\n  {\n    return std::chrono::seconds(v);\n  }\n};\n\nquantity q = 42s;\nstd::chrono::seconds dur = 42 * s;\n
    "},{"location":"users_guide/framework_basics/concepts/#PointOrigin","title":"PointOrigin<T>","text":"

    PointOrigin concept matches all quantity point origins in the library. It is satisfied by either:

    "},{"location":"users_guide/framework_basics/concepts/#PointOriginFor","title":"PointOriginFor<T, V>","text":"

    PointOriginFor concept is satisfied by all PointOrigin types that have quantity type implicitly convertible from quantity specification V, which means that V must satisfy QuantitySpecOf<T::quantity_spec>.

    Examples

    si::ice_point can serve as a point origin for points of isq::Celsius_temperature because this quantity type implicitly converts to isq::thermodynamic_temperature.

    However, if we define mean_sea_level in the following way:

    inline constexpr struct mean_sea_level final : absolute_point_origin<isq::altitude> {} mean_sea_level;\n

    then it can't be used as a point origin for points of isq::length or isq::width as none of them is implicitly convertible to isq::altitude:

    "},{"location":"users_guide/framework_basics/concepts/#QuantityPoint","title":"QuantityPoint<T>","text":"

    QuantityPoint concept is satisfied by all types being either a specialization or derived from quantity_point class template.

    "},{"location":"users_guide/framework_basics/concepts/#QuantityPointOf","title":"QuantityPointOf<T, V>","text":"

    QuantityPointOf concept is satisfied by all the quantity points T that match the following value V:

    V Condition QuantitySpec The quantity point quantity specification satisfies ReferenceOf<V> concept. PointOrigin The point and V have the same absolute point origin."},{"location":"users_guide/framework_basics/concepts/#QuantityPointLike","title":"QuantityPointLike<T>","text":"

    QuantityPointLike concept provides interoperability with other libraries and is satisfied by a type T for which an instantiation of quantity_point_like_traits type trait yields a valid type that provides:

    Examples

    This is how support for a std::chrono::time_point of std::chrono::seconds can be provided:

    template<typename C>\nstruct mp_units::quantity_point_like_traits<std::chrono::time_point<C, std::chrono::seconds>> {\n  static constexpr auto reference = si::second;\n  static constexpr struct point_origin_ final : absolute_point_origin<isq::time> {} point_origin{};\n  static constexpr bool explicit_import = false;\n  static constexpr bool explicit_export = false;\n  using rep = std::chrono::seconds::rep;\n  using T = std::chrono::time_point<C, std::chrono::seconds>;\n\n  [[nodiscard]] static constexpr rep to_numerical_value(const T& tp)\n  {\n    return tp.time_since_epoch().count();\n  }\n\n  [[nodiscard]] static constexpr T from_numerical_value(const rep& v)\n  {\n    return T(std::chrono::seconds(v));\n  }\n};\n\nquantity_point qp = time_point_cast<std::chrono::seconds>(std::chrono::system_clock::now());\nstd::chrono::sys_seconds q = qp + 42 * s;\n
    "},{"location":"users_guide/framework_basics/design_overview/","title":"Design Overview","text":"

    The most important entities in the mp-units library are:

    The graph provided below presents how those and a few other entities depend on each other:

    flowchart TD\n    Unit --- Reference\n    Dimension --- QuantitySpec[\"Quantity specification\"]\n    quantity_character[\"Quantity character\"] --- QuantitySpec\n    QuantitySpec --- Reference[\"Quantity reference\"]\n    Reference --- Quantity\n    quantity_character -.- Representation\n    Representation --- Quantity\n    Quantity --- QuantityPoint[\"Quantity point\"]\n    PointOrigin[\"Point origin\"] --- QuantityPoint\n\n    click Dimension \"#dimension\"\n    click quantity_character \"#quantity-character\"\n    click QuantitySpec \"#quantity-specification\"\n    click Unit \"#unit\"\n    click Reference \"#quantity-reference\"\n    click Representation \"#quantity-representation\"\n    click Quantity \"#quantity\"\n    click PointOrigin \"#point-origin\"\n    click QuantityPoint \"#quantity-point\"
    "},{"location":"users_guide/framework_basics/design_overview/#dimension","title":"Dimension","text":"

    Dimension specifies the dependence of a quantity on the base quantities of a particular system of quantities. It is represented as a product of powers of factors corresponding to the base quantities, omitting any numerical factor.

    In the mp-units library, we use the terms:

    For example:

    Base dimensions can be defined by the user in the following way:

    inline constexpr struct dim_length final : base_dimension<\"L\"> {} dim_length;\ninline constexpr struct dim_time final : base_dimension<\"T\"> {} dim_time;\n

    Derived dimensions are implicitly created by the library's framework based on the quantity equation provided in the quantity specification:

    C++23C++20Portable 
    inline constexpr struct length final : quantity_spec<dim_length> {} length;\ninline constexpr struct time final : quantity_spec<dim_time> {} time;\ninline constexpr struct speed final : quantity_spec<length / time> {} speed;\n\nstatic_assert(speed.dimension == dim_length / dim_time);\n
    inline constexpr struct length final : quantity_spec<length, dim_length> {} length;\ninline constexpr struct time final : quantity_spec<time, dim_time> {} time;\ninline constexpr struct speed final : quantity_spec<speed, length / time> {} speed;\n\nstatic_assert(speed.dimension == dim_length / dim_time);\n
    QUANTITY_SPEC(length, dim_length);\nQUANTITY_SPEC(time, dim_time);\nQUANTITY_SPEC(speed, length / time);\n\nstatic_assert(speed.dimension == dim_length / dim_time);\n

    Important

    Users should not explicitly define any derived dimensions. Those should always be implicitly created by the framework.

    The multiplication/division on quantity specifications also multiplies/divides their dimensions:

    static_assert((length / time).dimension == dim_length / dim_time);\n

    The dimension equation of isq::dim_length / isq::dim_time results in the derived_dimension<isq::dim_length, per<isq::dim_time>> type.

    "},{"location":"users_guide/framework_basics/design_overview/#quantity-character","title":"Quantity character","text":"

    ISO 80000 explicitly states that quantities (even of the same kind) may have different characters:

    The quantity character in the mp-units library is implemented with the quantity_character enumeration:

    enum class quantity_character { real_scalar, complex_scalar, vector, tensor };\n

    Info

    You can read more on quantity characters in the \"Character of a Quantity\" chapter.

    "},{"location":"users_guide/framework_basics/design_overview/#quantity-specification","title":"Quantity specification","text":"

    Dimension is not enough to describe a quantity. This is why the ISO 80000 provides hundreds of named quantity types. It turns out that there are many more quantity types in the ISQ than the named units in the SI.

    This is why the mp-units library introduces a quantity specification entity that stores:

    Note

    We know that it might be sometimes confusing to talk about quantities, quantity types/names, and quantity specifications. However, it might be important to notice here that even the ISO 80000 admits that:

    It is customary to use the same term, \"quantity\", to refer to both general quantities, such as length, mass, etc., and their instances, such as given lengths, given masses, etc. Accordingly, we are used to saying both that length is a quantity and that a given length is a quantity by maintaining the specification \u2013 \"general quantity, \\(Q\\)\" or \"individual quantity, \\(Q_\\textsf{a}\\)\" \u2013 implicit and exploiting the linguistic context to remove the ambiguity.

    In the mp-units library, we have a:

    For example:

    Quantity specification can be defined by the user in one of the following ways:

    C++23C++20Portable 
    inline constexpr struct length final : quantity_spec<dim_length> {} length;\ninline constexpr struct height final : quantity_spec<length> {} height;\ninline constexpr struct speed final : quantity_spec<length / time> {} speed;\n
    inline constexpr struct length final : quantity_spec<length, dim_length> {} length;\ninline constexpr struct height final : quantity_spec<height, length> {} height;\ninline constexpr struct speed final : quantity_spec<speed, length / time> {} speed;\n
    QUANTITY_SPEC(length, dim_length);\nQUANTITY_SPEC(height, length);\nQUANTITY_SPEC(speed, length / time);\n

    The quantity equation of isq::length / isq::time results in the derived_quantity_spec<isq::length, per<isq::time>> type.

    "},{"location":"users_guide/framework_basics/design_overview/#unit","title":"Unit","text":"

    A unit is a concrete amount of a quantity that allows us to measure the values of quantities of the same kind and represent the result as a number being the ratio of the two quantities.

    For example:

    Note

    In the mp-units library, physical constants are also implemented as units.

    A unit can be defined by the user in one of the following ways:

    template<PrefixableUnit U> struct kilo_ : prefixed_unit<\"k\", mag_power<10, 3>, U{}> {};\ntemplate<PrefixableUnit auto U> constexpr kilo_<decltype(U)> kilo;\n\ninline constexpr struct second final : named_unit<\"s\", kind_of<isq::time>> {} second;\ninline constexpr struct minute final : named_unit<\"min\", mag<60> * second> {} minute;\ninline constexpr struct gram   final : named_unit<\"g\", kind_of<isq::mass>> {} gram;\ninline constexpr auto kilogram = kilo<gram>;\ninline constexpr struct newton final : named_unit<\"N\", kilogram * metre / square(second)> {} newton;\n\ninline constexpr struct speed_of_light_in_vacuum final : named_unit<\"c\", mag<299'792'458> * metre / second> {} speed_of_light_in_vacuum;\n

    The unit equation of si::metre / si::second results in the derived_unit<si::metre, per<si::second>> type.

    "},{"location":"users_guide/framework_basics/design_overview/#quantity-reference","title":"Quantity reference","text":"

    ISO defines a quantity as:

    Quote

    property of a phenomenon, body, or substance, where the property has a magnitude that can be expressed as a number and a reference

    After that, it says:

    Quote

    A reference can be a measurement unit, a measurement procedure, a reference material, or a combination of such.

    In the mp-units library, a quantity reference provides all the domain-specific metadata for the quantity besides its numerical value:

    Together with the value of a representation type, it forms a quantity.

    In the library, we have two different ways to provide a reference:

    Note

    All the units of the SI have associated quantity kinds and may serve as a reference.

    For example:

    "},{"location":"users_guide/framework_basics/design_overview/#quantity-representation","title":"Quantity representation","text":"

    Quantity representation defines the type used to store the numerical value of a quantity. Such a type should be of a specific quantity character provided in the quantity specification.

    Note

    By default, all floating-point and integral (besides bool) types are treated as scalars.

    "},{"location":"users_guide/framework_basics/design_overview/#quantity","title":"Quantity","text":"

    ISO defines a quantity as:

    Quote

    property of a phenomenon, body, or substance, where the property has a magnitude that can be expressed as a number and a reference

    This is why a quantity class template is defined in the library as:

    template<Reference auto R,\n         RepresentationOf<get_quantity_spec(R)> Rep = double>\nclass quantity;\n

    Its value can be easily created by multiplying/dividing the numerical value and a reference.

    For example:

    "},{"location":"users_guide/framework_basics/design_overview/#point-origin","title":"Point origin","text":"

    In the affine space theory, the point origin specifies where the \"zero\" of our measurement's scale is.

    In the mp-units library, we have two types of point origins:

    For example:

    inline constexpr struct absolute_zero final : absolute_point_origin<isq::thermodynamic_temperature> {} absolute_zero;\n
    inline constexpr struct ice_point final : relative_point_origin<absolute_zero + 273'150 * milli<kelvin>> {} ice_point;\n
    "},{"location":"users_guide/framework_basics/design_overview/#quantity-point","title":"Quantity point","text":"

    Quantity point implements a point in the affine space theory.

    In the mp-units library, the quantity point is implemented as:

    template<Reference auto R,\n         PointOriginFor<get_quantity_spec(R)> auto PO,\n         RepresentationOf<get_quantity_spec(R)> Rep = double>\nclass quantity_point;\n

    Its value can be easily created by adding/subtracting the quantity with a point origin.

    For example:

    constexpr auto room_reference_temperature = ice_point + delta<isq::Celsius_temperature[deg_C]>(21);\n
    "},{"location":"users_guide/framework_basics/dimensionless_quantities/","title":"Dimensionless Quantities","text":"

    The quantities we discussed so far always had some specific type and physical dimension. However, this is not always the case. While performing various computations, we sometimes end up with so-called \"dimensionless\" quantities, which ISO defines as quantities of dimension one:

    ISO/IEC Guide 99

    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#dividing-two-quantities-of-the-same-kind","title":"Dividing two quantities of the same kind","text":"

    Dividing two quantities of the same kind always results in a quantity of dimension one. However, depending on what type of quantities we divide or what their units are, we may end up with slightly different results.

    Note

    In mp-units, dividing two quantities of the same dimension always results in a quantity with the dimension being dimension_one. This is often different for other physical units libraries, which may return a raw representation type for such cases. A raw value is also always returned from the division of two std::chrono::duration objects.

    To read more about the reasoning for this design decision, please check our FAQ.

    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#dividing-quantities-of-the-same-type","title":"Dividing quantities of the same type","text":"

    First, let's analyze what happens if we divide two quantities of the same type:

    constexpr QuantityOf<dimensionless> auto q = isq::height(200 * m) / isq::height(50 * m);\n

    In such a case, we end up with a dimensionless quantity that has the following properties:

    static_assert(q.quantity_spec == dimensionless);\nstatic_assert(q.dimension == dimension_one);\nstatic_assert(q.unit == one);\n

    In case we would like to print its value, we would see a raw value of 4 in the output with no unit being printed.

    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#dividing-quantities-of-different-types","title":"Dividing quantities of different types","text":"

    Now let's see what happens if we divide quantities of the same dimension and unit but which have different quantity types:

    constexpr QuantityOf<dimensionless> auto q = isq::work(200 * J) / isq::heat(50 * J);\n

    Again we end up with dimension_one and one, but this time:

    static_assert(q.quantity_spec == isq::work / isq::heat);\n

    As shown above, the result is not of a dimensionless type anymore. Instead, we get a quantity type derived from the performed quantity equation. According to the ISQ, work divided by heat is the recipe for the thermodynamic efficiency quantity, thus:

    static_assert(implicitly_convertible(q.quantity_spec, isq::efficiency_thermodynamics));\n

    Note

    The quantity of isq::efficiency_thermodynamics is of a kind dimensionless, so it is implicitly convertible to dimensionless and satisfies the QuantityOf<dimensionless> concept.

    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#dividing-quantities-of-different-units","title":"Dividing quantities of different units","text":"

    Now, let's see what happens when we divide two quantities of the same type but different units:

    constexpr QuantityOf<dimensionless> auto q = isq::height(4 * km) / isq::height(2 * m);\n

    This time, we still get a quantity of the dimensionless type with a dimension_one as its dimension. However, the resulting unit is not one anymore:

    static_assert(q.unit == mag_power<10, 3> * one);\n

    In case we would print the text output of this quantity, we would not see a raw value of 2000, but 2 km/m.

    First, it may look surprising, but this is consistent with dividing quantities of different dimensions. For example, if we divide 4 * km / 2 * s, we do not expect km to be \"expanded\" to m before the division, right? We would expect the result of 2 km/s, which is exactly what we get when we divide quantities of the same kind.

    This is a compelling feature that allows us to express huge or tiny ratios without the need for big and expensive representation types. With this, we can easily define things like a Hubble's constant that uses a unit that is proportional to the ratio of kilometers per megaparsecs, which are both units of length:

    inline constexpr struct hubble_constant final :\n    named_unit<{u8\"H\u2080\", \"H_0\"}, mag_ratio<701, 10> * si::kilo<si::metre> / si::second / si::mega<parsec>> {} hubble_constant;\n
    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#counts-of-things","title":"Counts of things","text":"

    Another important use case for dimensionless quantities is to provide strong types for counts of things. For example:

    Thanks to assigning strong names to such quantities, later on, they can be explicitly used as arguments in the quantity equations of other quantities deriving from them.

    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#predefined-units-of-the-dimensionless-quantity","title":"Predefined units of the dimensionless quantity","text":"

    As we observed above, the most common unit for dimensionless quantities is one. It has the ratio of 1 and does not output any textual symbol.

    Important: one is an identity

    A unit one is special in the entire type system of units as it is considered to be an identity operand in the unit symbolic expressions. This means that, for example:

    static_assert(one * one == one);\nstatic_assert(one * si::metre == si::metre);\nstatic_assert(si::metre / si::metre == one);\n

    The same is also true for dimension_one and dimensionless in the domains of dimensions and quantity specifications.

    Besides the unit one, there are a few other scaled units predefined in the library for usage with dimensionless quantities:

    inline constexpr struct percent final : named_unit<\"%\", mag_ratio<1, 100> * one> {} percent;\ninline constexpr struct per_mille final : named_unit<{u8\"\u2030\", \"%o\"}, mag_ratio<1, 1000> * one> {} per_mille;\ninline constexpr struct parts_per_million final : named_unit<\"ppm\", mag_ratio<1, 1'000'000> * one> {} parts_per_million;\ninline constexpr auto ppm = parts_per_million;\n
    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#superpowers-of-the-unit-one","title":"Superpowers of the unit one","text":"

    Quantities implicitly convertible to dimensionless with the unit equivalent to one are the only ones that are:

    quantity<one> inc(quantity<one> q) { return q + 1; }\nvoid legacy(double) { /* ... */ }\n\nif (auto q = inc(42); q != 0)\n  legacy(static_cast<int>(q));\n

    This property also expands to usual arithmetic operators.

    Note

    Those rules do not apply to all the dimensionless quantities. It would be unsafe and misleading to allow such operations on units with a magnitude different than 1 (e.g., percent) or for quantities that are not implicitly convertible to dimensionless (e.g., angular_measure).

    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#angular-quantities","title":"Angular quantities","text":"

    Special, often controversial, examples of dimensionless quantities are an angular measure and solid angular measure quantities that are defined in the ISQ to be the result of a division of \\(arc\\; length / radius\\) and \\(area / radius^2\\) respectively. Moreover, ISQ also explicitly states that both can be expressed in the unit one. This means that both angular measure and solid angular measure should be of a kind dimensionless.

    On the other hand, ISQ also specifies that a unit radian can be used for angular measure, and a unit steradian can be used for solid angular measure. Those should not be mixed or used to express other types of dimensionless quantities. This means that both angular measure and solid angular measure should also be quantity kinds by themselves.

    Note

    Many people claim that angle being a dimensionless quantity is a bad idea. There are proposals submitted to make an angle a base quantity and rad to become a base unit. More on this topic can be found in the \"Strong Angular System\" chapter.

    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#radians-and-degrees-support","title":"Radians and degrees support","text":"

    Thanks to the usage of magnitudes the library provides efficient strong types for all angular types. This means that with the built-in support for magnitudes of \\(\\pi\\) we can provide accurate conversions between radians and degrees. The library also provides common trigonometric functions for angular quantities:

    using namespace mp_units::si::unit_symbols;\nusing mp_units::angular::unit_symbols::rad;\nusing mp_units::angular::unit_symbols::deg;\nusing mp_units::angular::unit_symbols::grad;\n\nquantity speed = 110 * km / h;\nquantity rate_of_climb = -0.63657 * m / s;\nquantity glide_ratio = speed / -rate_of_climb;\nquantity glide_angle = angular::asin(1 / glide_ratio);\n\nstd::println(\"Glide ratio: {::N[.1f]}\", glide_ratio.in(one));\nstd::println(\"Glide angle:\");\nstd::println(\" - {::N[.4f]}\", glide_angle.in(rad));\nstd::println(\" - {::N[.2f]}\", glide_angle.in(deg));\nstd::println(\" - {::N[.2f]}\", glide_angle.in(grad));\n

    The above program prints:

    Glide ratio: 48.0\nGlide angle:\n - 0.0208 rad\n - 1.19\u00b0\n - 1.33\u1d4d\n

    Note

    In the production code the above speed and rate_of_climb quantities should probably be modelled as separate typed quantities of the same kind.

    "},{"location":"users_guide/framework_basics/dimensionless_quantities/#nested-quantity-kinds","title":"Nested quantity kinds","text":"

    Angular quantities are not the only ones with such a \"strange\" behavior. Another but a similar case is a storage capacity quantity specified in IEC-80000-13 that again allows expressing it in both one and bit units.

    Those cases make dimensionless quantities an exceptional tree in the library. This quantity hierarchy contains more than one quantity kind and more than one unit in its tree:

    flowchart TD\n    dimensionless[\"<b>dimensionless</b><br>[one]\"]\n    dimensionless --- rotation[\"<b>rotation</b>\"]\n    dimensionless --- thermodynamic_efficiency[\"<b>thermodynamic_efficiency</b><br><i>(work / heat)</i>\"]\n    dimensionless --- angular_measure[\"<b>angular_measure</b><br><i>(arc_length / radius)</i><br>[rad]\"]\n    angular_measure --- rotational_displacement[\"<b>rotational_displacement</b><br><i>(path_length / radius)</i>\"]\n    angular_measure --- phase_angle[\"<b>phase_angle</b>\"]\n    dimensionless --- solid_angular_measure[\"<b>solid_angular_measure</b><br><i>(area / pow<2>(radius))</i><br>[sr]\"]\n    dimensionless --- drag_factor[\"<b>drag_factor</b><br><i>(drag_force / (mass_density * pow<2>(speed) * area))</i>\"]\n    dimensionless --- storage_capacity[\"<b>storage_capacity</b><br>[bit]\"] --- equivalent_binary_storage_capacity[\"<b>equivalent_binary_storage_capacity</b>\"]\n    dimensionless --- ...

    To provide such support in the library, we provided an is_kind specifier that can be appended to the quantity specification:

    C++23C++20Portable 
    inline constexpr struct angular_measure final : quantity_spec<dimensionless, arc_length / radius, is_kind> {} angular_measure;\ninline constexpr struct solid_angular_measure final : quantity_spec<dimensionless, area / pow<2>(radius), is_kind> {} solid_angular_measure;\ninline constexpr struct storage_capacity final : quantity_spec<dimensionless, is_kind> {} storage_capacity;\n
    inline constexpr struct angular_measure final : quantity_spec<angular_measure, dimensionless, arc_length / radius, is_kind> {} angular_measure;\ninline constexpr struct solid_angular_measure final : quantity_spec<solid_angular_measure, dimensionless, area / pow<2>(radius), is_kind> {} solid_angular_measure;\ninline constexpr struct storage_capacity final : quantity_spec<storage_capacity, dimensionless, is_kind> {} storage_capacity;\n
    QUANTITY_SPEC(angular_measure, dimensionless, arc_length / radius, is_kind);\nQUANTITY_SPEC(solid_angular_measure, dimensionless, area / pow<2>(radius), is_kind);\nQUANTITY_SPEC(storage_capacity, dimensionless, is_kind);\n

    With the above, we can constrain radian, steradian, and bit to be allowed for usage with specific quantity kinds only:

    inline constexpr struct radian final : named_unit<\"rad\", metre / metre, kind_of<isq::angular_measure>> {} radian;\ninline constexpr struct steradian final : named_unit<\"sr\", square(metre) / square(metre), kind_of<isq::solid_angular_measure>> {} steradian;\ninline constexpr struct bit final : named_unit<\"bit\", one, kind_of<storage_capacity>> {} bit;\n

    but still allow the usage of one and its scaled versions for such quantities.

    Info

    It is worth mentioning here that converting up the hierarchy beyond a subkind requires an explicit conversion. For example:

    static_assert(implicitly_convertible(isq::rotation, dimensionless));\nstatic_assert(!implicitly_convertible(isq::angular_measure, dimensionless));\nstatic_assert(explicitly_convertible(isq::angular_measure, dimensionless));\n

    This increases type safety and prevents accidental quantities with invalid units. For example, a result of a conversion from isq::angular_measure[rad] to dimensionless would be a reference of dimensionless[rad], which contains an incorrect unit for a dimensionless quantity. Such a conversion must be explicit and be preceded by an explicit unit conversion:

    quantity q1 = isq::angular_measure(42. * rad);\nquantity<dimensionless[one]> q2 = dimensionless(q1.in(one));\n
    "},{"location":"users_guide/framework_basics/faster_than_lightspeed_constants/","title":"Faster-than-lightspeed Constants","text":"

    In most libraries, physical constants are implemented as constant (possibly constexpr) quantity values. Such an approach has some disadvantages, often affecting the run time performance and causing a loss of precision.

    "},{"location":"users_guide/framework_basics/faster_than_lightspeed_constants/#simplifying-constants-in-an-equation","title":"Simplifying constants in an equation","text":"

    When dealing with equations involving physical constants, they often occur more than once in an expression. Such a constant may appear both in a numerator and denominator of a quantity equation. As we know from fundamental physics, we can simplify such an expression by striking a constant out of the equation. Supporting such behavior allows a faster runtime performance and often a better precision of the resulting value.

    "},{"location":"users_guide/framework_basics/faster_than_lightspeed_constants/#physical-constants-as-units","title":"Physical constants as units","text":"

    The mp-units library allows and encourages the implementation of physical constants as regular units. With that, the constant's value is handled at compile-time, and under favorable circumstances, it can be simplified in the same way as all other repeated units do. If it is not simplified, the value is stored in a type, and the expensive multiplication or division operations can be delayed in time until a user selects a specific unit to represent/print the data.

    Such a feature often also allows using simpler or faster representation types in the equation. For example, instead of always having to multiply a small integral value with a big floating-point constant number, we can just use the integral type all the way. Only in case a constant will not simplify in the equation, and the user will require a specific unit, such a multiplication will be lazily invoked, and the representation type will need to be expanded to facilitate that. With that, addition, subtractions, multiplications, and divisions will always be the fastest - compiled away or done in out-of-order execution.

    To benefit from all of the above, in the mp-units library, SI defining and other constants are implemented as units in the following way:

    namespace si {\n\nnamespace si2019 {\n\ninline constexpr struct speed_of_light_in_vacuum final :\n  named_unit<\"c\", mag<299'792'458> * metre / second> {} speed_of_light_in_vacuum;\n\n}  // namespace si2019\n\ninline constexpr struct magnetic_constant final :\n  named_unit<{u8\"\u03bc\u2080\", \"u_0\"}, mag<4> * mag<\u03c0> * mag_power<10, -7> * henry / metre> {} magnetic_constant;\n\n}  // namespace mp_units::si\n
    "},{"location":"users_guide/framework_basics/faster_than_lightspeed_constants/#usage-examples","title":"Usage examples","text":"

    With the above definitions, we can calculate vacuum permittivity as:

    constexpr auto permeability_of_vacuum = 1. * si::magnetic_constant;\nconstexpr auto speed_of_light_in_vacuum = 1 * si::si2019::speed_of_light_in_vacuum;\n\nQuantityOf<isq::permittivity_of_vacuum> auto q = 1 / (permeability_of_vacuum * pow<2>(speed_of_light_in_vacuum));\n\nstd::println(\"permittivity of vacuum = {} = {::N[.3e]}\", q, q.in(F / m));\n

    The above first prints the following:

    permittivity of vacuum = 1  \u03bc\u2080\u207b\u00b9 c\u207b\u00b2 = 8.854e-12 F/m\n

    As we can clearly see, all the calculations above were just about multiplying and dividing the number 1 with the rest of the information provided as a compile-time type. Only when a user wants a specific SI unit as a result, the unit ratios are lazily resolved.

    Another similar example can be an equation for total energy:

    QuantityOf<isq::mechanical_energy> auto total_energy(QuantityOf<isq::momentum> auto p,\n                                                     QuantityOf<isq::mass> auto m,\n                                                     QuantityOf<isq::speed> auto c)\n{\n  return isq::mechanical_energy(sqrt(pow<2>(p * c) + pow<2>(m * pow<2>(c))));\n}\n
    constexpr auto GeV = si::giga<si::electronvolt>;\nconstexpr QuantityOf<isq::speed> auto c = 1. * si::si2019::speed_of_light_in_vacuum;\nconstexpr auto c2 = pow<2>(c);\n\nconst auto p1 = isq::momentum(4. * GeV / c);\nconst QuantityOf<isq::mass> auto m1 = 3. * GeV / c2;\nconst auto E = total_energy(p1, m1, c);\n\nstd::cout << \"in `GeV` and `c`:\\n\"\n          << \"p = \" << p1 << \"\\n\"\n          << \"m = \" << m1 << \"\\n\"\n          << \"E = \" << E << \"\\n\";\n\nconst auto p2 = p1.in(GeV / (m / s));\nconst auto m2 = m1.in(GeV / pow<2>(m / s));\nconst auto E2 = total_energy(p2, m2, c).in(GeV);\n\nstd::cout << \"\\nin `GeV`:\\n\"\n          << \"p = \" << p2 << \"\\n\"\n          << \"m = \" << m2 << \"\\n\"\n          << \"E = \" << E2 << \"\\n\";\n\nconst auto p3 = p1.in(kg * m / s);\nconst auto m3 = m1.in(kg);\nconst auto E3 = total_energy(p3, m3, c).in(J);\n\nstd::cout << \"\\nin SI base units:\\n\"\n          << \"p = \" << p3 << \"\\n\"\n          << \"m = \" << m3 << \"\\n\"\n          << \"E = \" << E3 << \"\\n\";\n

    The above prints the following:

    in `GeV` and `c`:\np = 4 GeV/c\nm = 3 GeV/c\u00b2\nE = 5 GeV\n\nin `GeV`:\np = 1.33426e-08 GeV s/m\nm = 3.33795e-17 GeV s\u00b2/m\u00b2\nE = 5 GeV\n\nin SI base units:\np = 2.13771e-18 kg m/s\nm = 5.34799e-27 kg\nE = 8.01088e-10 J\n
    "},{"location":"users_guide/framework_basics/generic_interfaces/","title":"Generic Interfaces","text":"

    Using a concrete unit in the interface often makes a lot of sense. It is especially useful if we store the data internally in the object. In such a case, we have to select a specific unit anyway.

    For example, let's consider a simple storage tank:

    class StorageTank {\n  quantity<horizontal_area[m2]> base_;\n  quantity<isq::height[m]> height_;\n  quantity<isq::mass_density[kg / m3]> density_ = air_density;\npublic:\n  constexpr StorageTank(const quantity<horizontal_area[m2]>& base, const quantity<isq::height[m]>& height) :\n      base_(base), height_(height)\n  {\n  }\n\n  // ...\n};\n

    As the quantities provided in the function's interface are then stored in the class, there is probably no sense in using generic interfaces here.

    "},{"location":"users_guide/framework_basics/generic_interfaces/#the-issues-with-unit-specific-interfaces","title":"The issues with unit-specific interfaces","text":"

    However, in many cases, using a specific unit in the interface is counterproductive. Let's consider the following function:

    quantity<km / h> avg_speed(quantity<km> distance, quantity<h> duration)\n{\n  return distance / duration;\n}\n

    Everything seems fine for now. It also works great if we call it with:

    quantity<km / h> s1 = avg_speed(220 * km, 2 * h);\n

    However, if the user starts doing the following:

    quantity<mi / h> s2 = avg_speed(140 * mi, 2 * h);\nquantity<m / s> s3 = avg_speed(20 * m, 2 * s);\n

    some issues start to be clearly visible:

    1. The arguments must be converted to units mandated by the function's parameters at each call. This involves potentially expensive multiplication/division operations at runtime.
    2. After the function returns the speed in a unit of km/h, another potentially expensive multiplication/division operations must be performed to convert the resulting quantity into a unit being the derived unit of the initial function's arguments.
    3. Besides the obvious runtime cost, some unit conversions may result in a value truncation, which means that the result will not be exactly equal to a direct division of the function's arguments.

    4. We have to use a floating-point representation type (the quantity class template by default uses double as a representation type) which is considered value-preserving. Trying to use an integral type in this scenario will work only for s1, while s2 and s3 will fail to compile. Failing to compile is a good thing here as the library tries to prevent the user from doing a clearly wrong thing. To make the code compile, the user needs to use dedicated value_cast or force_in like this:

      quantity<isq::speed[mi / h]> s2 = avg_speed(value_cast<km>(140 * mi), 2 * h);\nquantity<isq::speed[m / s]> s3 = avg_speed((20 * m).force_in(km), (2 * s).force_in(h));\n

      but the above will obviously provide an incorrect behavior (e.g., division by 0 in the evaluation of s3).

    "},{"location":"users_guide/framework_basics/generic_interfaces/#a-naive-solution","title":"A naive solution","text":"

    A naive solution here would be to implement the function as an unconstrained function template:

    auto avg_speed(auto distance, auto duration)\n{\n  return distance / duration;\n}\n

    Beware, this is not a good solution. The above code is too generic. Such a function template accepts everything:

    Note

    The usage of auto instead of a function parameter type is a C++20 feature. It makes such a code a function template where the type of such a parameter will be deduced during the template instantiation process from the argument type passed by the user.

    "},{"location":"users_guide/framework_basics/generic_interfaces/#constraining-function-template-arguments-with-concepts","title":"Constraining function template arguments with concepts","text":"

    Much better generic code can be implemented using basic concepts provided with the library:

    Original template notationThe shorthand notationTerse notation 
    template<typename Distance, typename Duration>\n  requires QuantityOf<Distance, isq::length> && QuantityOf<Duration, isq::time>\nauto avg_speed(Distance distance, Duration duration)\n{\n  return isq::speed(distance / duration);\n}\n
    template<QuantityOf<isq::length> Distance, QuantityOf<isq::time> Duration>\nauto avg_speed(Distance distance, Duration duration)\n{\n  return isq::speed(distance / duration);\n}\n
    auto avg_speed(QuantityOf<isq::length> auto distance,\n               QuantityOf<isq::time> auto duration)\n{\n  return isq::speed(distance / duration);\n}\n

    This explicitly states that the arguments passed by the user must not only satisfy a Quantity concept, but also their quantity specification must be implicitly convertible to isq::length and isq::time accordingly. This no longer leaves room for error while still allowing the compiler to generate the most efficient code.

    Tip

    Please note that now it is safe just to use integral types all the way which again improves the runtime performance as the multiplication/division operations are often faster on the integral rather than floating-point types.

    "},{"location":"users_guide/framework_basics/generic_interfaces/#constraining-function-template-return-type","title":"Constraining function template return type","text":"

    The above function template resolves all of the issues described before. However, we can do even better here by additionally constraining the return type:

    QuantityOf<isq::speed> auto avg_speed(QuantityOf<isq::length> auto distance,\n                                      QuantityOf<isq::time> auto duration)\n{\n  return isq::speed(distance / duration);\n}\n

    Doing so has two important benefits:

    1. It informs the users of our interface about what to expect to be the result of a function invocation. It is superior to just returning auto, which does not provide any hint about the thing being returned there.
    2. Such a concept constrains the type returned from the function. This means that it works as a unit test to verify if our function actually performs what it is supposed to do. If there is an error in quantity equations, we will learn about it right away.
    "},{"location":"users_guide/framework_basics/generic_interfaces/#constraining-a-variable-on-the-stack","title":"Constraining a variable on the stack","text":"

    If we know precisely what the function does in its internals and if we know the exact argument types passed to such a function, we often know the exact type that will be returned from its invocation.

    However, if we care about performance, we should often use the generic interfaces described in this chapter. A side effect is that we sometimes are unsure about the return type. Even if we know it today, it might change a week from now due to some code refactoring.

    In such cases, we can again use auto to denote the type:

    auto s1 = avg_speed(220 * km, 2 * h);\nauto s2 = avg_speed(140 * mi, 2 * h);\nauto s3 = avg_speed(20 * m, 2 * s);\n

    or benefit from CTAD:

    quantity s1 = avg_speed(220 * km, 2 * h);\nquantity s2 = avg_speed(140 * mi, 2 * h);\nquantity s3 = avg_speed(20 * m, 2 * s);\n

    In both cases, it is probably OK to do so as the avg_speed function name explicitly provides the information on what to expect as a result.

    In other scenarios where the returned quantity type is not so obvious, it is again helpful to constrain the type with a concept like so:

    QuantityOf<isq::speed> auto s1 = avg_speed(220 * km, 2 * h);\nQuantityOf<isq::speed> auto s2 = avg_speed(140 * mi, 2 * h);\nQuantityOf<isq::speed> auto s3 = avg_speed(20 * m, 2 * s);\n

    The above explicitly provides additional information about the quantity we are dealing with in the code, and it serves as a unit test checking if the \"thing\" returned from a function is actually what we expected here.

    Note

    The QuantityOf and QuantityPointOf concepts are probably the most useful, but there are a few more to play with. A list of all the concepts can be found in the Basic Concepts chapter.

    "},{"location":"users_guide/framework_basics/interface_introduction/","title":"Interface Introduction","text":""},{"location":"users_guide/framework_basics/interface_introduction/#new-style-of-definitions","title":"New style of definitions","text":"

    The mp-units library decided to use a rather unusual pattern to define entities. Here is how we define metre and second SI base units:

    inline constexpr struct metre final : named_unit<\"m\", kind_of<isq::length>> {} metre;\ninline constexpr struct second final : named_unit<\"s\", kind_of<isq::time>> {} second;\n

    Please note that the above reuses the same identifier for a type and its value. The rationale behind this is that:

    Important

    To improve compiler errors' readability and make it easier to correlate them with a user's written code, a new idiom in the library is to use the same identifier for a type and its instance.

    Also, to prevent possible issues in compile-time logic, all of the library's entities must be marked final. This prevents the users to derive own strong types from them, which would prevent symbolic expressions simplification of equivalent entities.

    "},{"location":"users_guide/framework_basics/interface_introduction/#strong-types-instead-of-aliases","title":"Strong types instead of aliases","text":"

    Let's look again at the above units definitions. Another important point to notice is that all the types describing entities in the library are short, nicely named identifiers that derive from longer, more verbose class template instantiations. This is really important to improve the user experience while debugging the program or analyzing the compilation error.

    Note

    Such a practice is rare in the industry. Some popular C++ physical units libraries generate enormously long error messages where even only the first line failed to fit on a slide with a tiny font.

    "},{"location":"users_guide/framework_basics/interface_introduction/#entities-composability","title":"Entities composability","text":"

    Many physical units libraries (in C++ or any other programming language) assign strong types to library entities (e.g., derived units). While metre_per_second as a type may not look too scary, consider, for example, units of angular momentum. If we followed this path, its coherent unit would look like kilogram_metre_sq_per_second. Now, consider how many scaled versions of this unit you would predefine in the library to ensure that all users are happy with your choice? How expensive would it be from the implementation point of view? What about potential future standardization efforts?

    This is why in mp-units, we put a strong requirement to make everything as composable as possible. For example, to create a quantity with a unit of speed, one may write:

    quantity<si::metre / si::second> q;\n

    In case we use such a unit often and would prefer to have a handy helper for it, we can always do something like this:

    constexpr auto metre_per_second = si::metre / si::second;\nquantity<metre_per_second> q;\n

    or choose any shorter identifier of our choice.

    Coming back to the angular momentum case, thanks to the composability of units, a user can create such a quantity in the following way:

    using namespace mp_units::si::unit_symbols;\nauto q = la_vector{1, 2, 3} * isq::angular_momentum[kg * m2 / s];\n

    It is a much better solution. It is terse and easy to understand. Please also notice how easy it is to obtain any scaled version of such a unit (e.g., mg * square(mm) / min) without having to introduce hundreds of types to predefine them.

    "},{"location":"users_guide/framework_basics/interface_introduction/#value-based-equations","title":"Value-based equations","text":"

    The mp-units library is based on C++20, significantly improving user experience. One of such improvements is the usage of value-based equations.

    As we have learned above, the entities are being used as values in the code, and they compose. Moreover, derived entities can be defined in the library using such value-based equations. This is a huge improvement compared to what we can find in other physical units libraries or what we have to deal with when we want to write some equations for std::ratio.

    For example, below are a few definitions of the SI derived units showing the power of C++20 extensions to Non-Type Template Parameters, which allow us to directly pass a result of the value-based unit equation to a class template definition:

    inline constexpr struct newton final : named_unit<\"N\", kilogram * metre / square(second)> {} newton;\ninline constexpr struct pascal final : named_unit<\"Pa\", newton / square(metre)> {} pascal;\ninline constexpr struct joule  final : named_unit<\"J\", newton * metre> {} joule;\n
    "},{"location":"users_guide/framework_basics/interface_introduction/#symbolic-expressions","title":"Symbolic expressions","text":"

    The previous chapter provided a rationale for not having predefined types for derived entities. In many libraries, such an approach results in long and unreadable compilation errors, as framework-generated types are typically far from being easy to read and understand.

    The mp-units library greatly improves the user experience by extensively using symbolic expressions. Such expressions are used consistently throughout the entire library to describe the results of:

    For example, if we take the above-defined base units and put the results of their division into the quantity class template like this:

    quantity<metre / second> q;\n

    we will observe the following type in the debugger

    (gdb) ptype q\ntype = class mp_units::quantity<mp_units::derived_unit<metre, mp_units::per<second>>(), double> [with Rep = double] {\n

    The same type identifier will be visible in the compilation error (in case it happens).

    Important

    Expressions templates are extensively used throughout the library to improve the readability of the resulting types.

    "},{"location":"users_guide/framework_basics/interface_introduction/#identities","title":"Identities","text":"

    As mentioned above, equations can be performed on dimensions, quantities, and units. Each such domain must introduce an identity object that can be used in the resulting expressions. Here is the list of identities used in the library:

    Domain Concept Identity Dimension dimension_one QuantitySpec dimensionless Unit one

    In the equations, a user can explicitly refer to an identity object. For example:

    constexpr auto my_unit = one / second;\n

    Note

    Another way to achieve the same result is to call an inverse() function:

    constexpr auto my_unit = inverse(second);\n

    Both cases will result in the same symbolic expression being generated and put into the wrapper class template.

    "},{"location":"users_guide/framework_basics/interface_introduction/#supported-operations-and-their-results","title":"Supported operations and their results","text":"

    There are only a few operations that one can do on such entities, and the result of each of them has its unique representation in the library:

    Operation Resulting template expression arguments A * B A, B B * A A, B A * A power<A, 2> {identity} * A A A * {identity} A A / B A, per<B> A / A {identity} A / {identity} A {identity} / A {identity}, per<A> pow<2>(A) power<A, 2> pow<2>({identity}) {identity} sqrt(A) or pow<1, 2>(A) power<A, 1, 2> sqrt({identity}) or pow<1, 2>({identity}) {identity}"},{"location":"users_guide/framework_basics/interface_introduction/#simplifying-the-resulting-symbolic-expressions","title":"Simplifying the resulting symbolic expressions","text":"

    To limit the length and improve the readability of generated types, there are many rules to simplify the resulting symbolic expression.

    1. Ordering

      The resulting comma-separated arguments of multiplication are always sorted according to a specific predicate. This is why:

      static_assert(A * B == B * A);\nstatic_assert(std::is_same_v<decltype(A * B), decltype(B * A)>);\n

      This is probably the most important of all the steps, as it allows comparing types and enables the rest of the simplification rules.

    2. Aggregation

      In case two of the same identifiers are found next to each other on the argument list they will be aggregated in one entry:

      Before After A, A power<A, 2> A, power<A, 2> power<A, 3> power<A, 1, 2>, power<A, 2> power<A, 5, 2> power<A, 1, 2>, power<A, 1, 2> A

    3. Simplification

      In case two of the same identifiers are found in the numerator and denominator argument lists; they are being simplified into one entry:

      Before After A, per<A> {identity} power<A, 2>, per<A> A power<A, 3>, per<A> power<A, 2> A, per<power<A, 2>> {identity}, per<A>

      It is important to notice here that only the elements with exactly the same type are being simplified. This means that, for example, m/m results in one, but km/m will not be simplified. The resulting derived unit will preserve both symbols and their relative magnitude. This allows us to properly print symbols of some units or constants that require such behavior. For example, the Hubble constant is expressed in km\u22c5s\u207b\u00b9\u22c5Mpc\u207b\u00b9, where both km and Mpc are units of length.

      Also, to prevent possible issues in compile-time logic, all of the library's entities must be marked final. This prevents the users to derive own strong types from them, which would prevent symbolic expression simplification of equivalent entities.

    4. Repacking

      In case an expression uses two results of other operations, the components of its arguments are repacked into one resulting type and simplified there.

      For example, assuming:

      constexpr auto X = A / B;\n

      then:

      Operation Resulting template expression arguments X * B A X * A power<A, 2>, per<B> X * X power<A, 2>, per<power<B, 2>> X / X {identity} X / A {identity}, per<B> X / B A, per<power<B, 2>>
    "},{"location":"users_guide/framework_basics/interface_introduction/#example","title":"Example","text":"

    Thanks to all of the features described above, a user may write the code like this one:

    using namespace mp_units::si::unit_symbols;\nquantity speed = 60. * isq::speed[km / h];\nquantity duration = 8 * s;\nquantity acceleration = speed / duration;\nstd::cout << \"acceleration: \" << acceleration << \" (\" << acceleration.in(m / s2) << \")\\n\";\n

    The acceleration quantity, being the result of the above code, has the following type (after stripping the mp_units namespace for brevity):

    quantity<reference<derived_quantity_spec<isq::speed, per<isq::time>>{}, derived_unit<si::kilo_<si::metre{}>, per<non_si::hour, si::second>>{}>{}, int>\n

    and the text output presents:

    acceleration: 7.5 km h\u207b\u00b9 s\u207b\u00b9 (2.08333 m/s\u00b2)\n
    "},{"location":"users_guide/framework_basics/obtaining_metadata/","title":"Obtaining Metadata","text":""},{"location":"users_guide/framework_basics/obtaining_metadata/#quantity-spec","title":"quantity spec","text":""},{"location":"users_guide/framework_basics/obtaining_metadata/#unit","title":"unit","text":""},{"location":"users_guide/framework_basics/obtaining_metadata/#reference","title":"reference","text":""},{"location":"users_guide/framework_basics/obtaining_metadata/#quantity","title":"quantity","text":""},{"location":"users_guide/framework_basics/quantity_arithmetics/","title":"Quantity Arithmetics","text":""},{"location":"users_guide/framework_basics/quantity_arithmetics/#quantity-is-a-numeric-wrapper","title":"quantity is a numeric wrapper","text":"

    If we think about it, the quantity class template is just a \"smart\" numeric wrapper. It exposes properly constrained set of arithmetic operations on one or two operands.

    Important: quantity propagates the underlying interface

    Every single arithmetic operator is exposed by the quantity class template only if the underlying representation type provides it as well, and when its implementation has proper semantics (e.g., returns a reasonable type).

    For example, in the following code, -a will compile only if MyInt exposes such an operation as well:

    quantity a = MyInt{42} * m;\nquantity b = -a;\n

    Assuming that:

    here is the list of all the supported operators:

    As we can see, there are plenty of operations one can do on a value of a quantity type. As most of them are obvious, in the following chapters, we will discuss only the most important or non-trivial aspects of quantity arithmetics.

    "},{"location":"users_guide/framework_basics/quantity_arithmetics/#addition-and-subtraction","title":"Addition and subtraction","text":"

    Quantities can easily be added or subtracted from each other:

    static_assert(1 * m + 1 * m == 2 * m);\nstatic_assert(2 * m - 1 * m == 1 * m);\nstatic_assert(isq::height(1 * m) + isq::height(1 * m) == isq::height(2 * m));\nstatic_assert(isq::height(2 * m) - isq::height(1 * m) == isq::height(1 * m));\n

    The above uses the same types for LHS, RHS, and the result, but in general, we can add, subtract, or compare the values of any quantity type as long as both quantities are of the same kind. The result of such an operation will be the common type of the arguments:

    static_assert(1 * km + 1.5 * m == 1001.5 * m);\nstatic_assert(isq::height(1 * m) + isq::width(1 * m) == isq::length(2 * m));\nstatic_assert(isq::height(2 * m) - isq::distance(0.5 * m) == 1.5 * m);\nstatic_assert(isq::radius(1 * m) - 0.5 * m == isq::radius(0.5 * m));\n

    Note

    Please note that for the compound assignment operators, we always need to end up with the left-hand-side argument type:

    static_assert((1 * m += 1 * km) == 1001 * m);\nstatic_assert((isq::length(1 * m) += isq::height(1 * m)) == isq::length(1 * m));\nstatic_assert((isq::height(1.5 * m) -= 1 * m) == isq::height(0.5 * m));\n

    If we will break typical library's convertibility rules, the following code will not compile:

    quantity q1 = 1 * m -= 0.5 * m;                         // Compile-time error(1)\nquantity q2 = 1 * km += 1 * m;                          // Compile-time error(2)\nquantity q3 = isq::height(1 * m) += isq::length(1 * m); // Compile-time error(3)\n
    1. Conversion of the floating-point to integral representation type is considered narrowing.
    2. Conversion of quantity with integral representation type from a unit of a higher resolution to the one with a lower resolution is considered narrowing.
    3. Conversion from a more generic quantity type to a more specific one is considered unsafe.
    "},{"location":"users_guide/framework_basics/quantity_arithmetics/#multiplication-and-division","title":"Multiplication and division","text":"

    Multiplying or dividing a quantity by a number does not change its quantity type or unit. However, its representation type may change. For example:

    static_assert(isq::height(3 * m) * 0.5 == isq::height(1.5 * m));\n

    Note

    Unless we use a compound assignment operator, in which case we always have to result with the type of the left-hand-side argument. This, together with the fact that this library tries to prevent truncation of a quantity value means, that the following does not compile:

    quantity q = isq::height(3 * m) *= 0.5; // Compile-time error\n

    However, suppose we multiply or divide quantities of the same or different types or we divide a raw number by a quantity. In that case, we most probably will end up in a quantity of yet another type:

    static_assert(120 * km / (2 * h) == 60 * km / h);\nstatic_assert(isq::width(2 * m) * isq::length(2 * m) == isq::area(4 * m2));\nstatic_assert(50 / isq::time(1 * s) == isq::frequency(50 * Hz));\n

    Note

    An exception from the above rule happens when one of the arguments is a dimensionless quantity. If we multiply or divide by such a quantity, the quantity type will not change. If such a quantity has a unit one, also the unit of a quantity will not change:

    static_assert(120 * m / (2 * one) == 60 * m);\n

    An interesting special case happens when we divide the same quantity kinds or multiply a quantity by its inverted type. In such a case, we end up with a dimensionless quantity.

    static_assert(isq::height(4 * m) / isq::width(2 * m) == 2 * one); // (1)!\nstatic_assert(5 * h / (120 * min) == 0 * one);  // (2)!\nstatic_assert(5. * h / (120 * min) == 2.5 * one);\n
    1. The resulting quantity type of the LHS is isq::height / isq::width, which is a quantity of the dimensionless kind.
    2. The resulting quantity of the LHS is 0 * dimensionless[h / min]. To be consistent with the division of different quantity types, we do not convert quantity values to a common unit before the division.

    Important: Beware of integral division

    The physical units library can't do any runtime branching logic for the division operator. All logic must be done at compile-time when the actual values are unknown, and the quantity types can't change at runtime.

    If we expect 120 * km / (2 * h) to return 60 km / h, we have to agree with the fact that 5 * km / (24 * h) returns 0 km/h. We can't do a range check at runtime to dynamically adjust scales and types based on the values of provided function arguments.

    This is why we often prefer floating-point representation types when dealing with units. Some popular physical units libraries even forbid integer division at all.

    "},{"location":"users_guide/framework_basics/quantity_arithmetics/#modulo","title":"Modulo","text":"

    Now that we know how addition, subtraction, multiplication, and division work, it is time to discuss modulo. What would we expect to be returned from the following quantity equation?

    auto q = 5 * h % (120 * min);\n

    Most of us would probably expect to see 1 h or 60 min as a result. And this is where the problems start.

    C++ language defines its / and % operators with the quotient-remainder theorem:

    q = a / b;\nr = a % b;\nq * b + r == a;\n

    The important property of the modulo operation is that it only works for integral representation types (it is undefined what modulo for floating-point types means). However, as we saw in the previous chapter, integral types are tricky because they often truncate the value.

    From the quotient-remainder theorem, the result of modulo operation is r = a - q * b. Let's see what we get from such a quantity equation on integral representation types:

    const quantity a = 5 * h;\nconst quantity b = 120 * min;\nconst quantity q = a / b;\nconst quantity r = a - q * b;\n\nstd::cout << \"reminder: \" << r << \"\\n\";\n

    The above code outputs:

    reminder: 5 h\n

    And now, a tough question needs an answer. Do we really want modulo operation on physical units to be consistent with the quotient-remainder theorem and return 5 h for 5 * h % (120 * min)?

    This is exactly why we decided not to follow this hugely surprising path in the mp-units library. The selected approach was also consistent with the feedback from the C++ experts. For example, this is what Richard Smith said about this issue:

    Richard Smith

    I think the quotient-remainder property is a less important motivation here than other factors -- the constraints on % and / are quite different, so they lack the inherent connection they have for integers. In particular, I would expect that A / B works for all quantities A and B, whereas A % B is only meaningful when A and B have the same dimension. It seems like a nice-to-have for the property to apply in the case where both / and % are defined, but internal consistency of / across all cases seems much more important to me.

    I would expect 61 min % 1 h to be 1 min, and 1 h % 59 min to also be 1 min, so my intuition tells me that the result type of A % B, where A and B have the same dimension, should have the smaller unit of A and B (and if the smaller one doesn't divide the larger one, we should either use the gcd / std::common_type of the units of A and B or perhaps just produce an error). I think any other behavior for % is hard to defend.

    On the other hand, for division it seems to me that the choice of unit should probably not affect the result, and so if we want that 5 mm / 120 min = 0 mm/min, then 5 h / 120 min == 0 hc (where hc is a dimensionless \"hexaconta\", or 60x, unit). I don't like the idea of taking SI base units into account; that seems arbitrary and like it would do the wrong thing as often as it does the right thing, especially when the units have a multiplier that is very large or small. We could special-case the situation of a dimensionless quantity, but that could lead to problematic overflow pretty easily: a calculation such as 10 s * 5 GHz * 2 uW would overflow an int if it produces a dimensionless quantity for 10 s * 5 GHz, but it could equally produce 50 G * 2 uW = 100 kW without any overflow, and presumably would if the terms were merely reordered.

    If people want to use integer-valued quantities, I think it's fundamental that you need to know what the units of the result of an operation will be, and take that into account in how you express computations; the simplest rule for heterogeneous operators like * or / seems to be that the units of the result are determined by applying the operator to the units of the operands -- and for homogeneous operators like + or %, it seems like the only reasonable option is that you get the std::common_type of the units of the operands.

    To summarize, the modulo operation on physical units has more in common with addition and division operators than with the quotient-remainder theorem. To avoid surprising results, the operation uses a common unit to do the calculation and provide its result:

    static_assert(5 * h / (120 * min) == 0 * one);\nstatic_assert(5 * h % (120 * min) == 60 * min);\nstatic_assert(61 * min % (1 * h) == 1 * min);\nstatic_assert(1 * h % (59 * min) == 1 * min);\n
    "},{"location":"users_guide/framework_basics/quantity_arithmetics/#comparison-against-zero","title":"Comparison against zero","text":"

    In our code, we often want to compare the value of a quantity against zero. For example, we do it every time we want to ensure that we deal with a non-zero or positive value.

    We could implement such checks in the following way:

    if (q1 / q2 != 0 * m / s)\n  // ...\n

    The above would work (assuming we are dealing with the quantity of speed) but could be suboptimal if the result of q1 / q2 is not expressed in m / s. To eliminate the need for conversion, we need to write:

    if (auto q = q1 / q2; q != q.zero())\n  // ...\n

    but that is a bit inconvenient, and inexperienced users could be unaware of this technique and its reasons.

    For the above reasons, the library provides dedicated interfaces to compare against zero that follow the naming convention of named comparison functions in the C++ Standard Library. The mp-units/compare.h header file exposes the following functions:

    Thanks to them, to save typing and not pay for unneeded conversions, our check could be implemented as follows:

    if (is_neq_zero(q1 / q2))\n  // ...\n

    Tip

    Those functions will work with any type T that exposes zero() member function returning something comparable to T. Thanks to that, we can use them not only with quantities but also with std::chrono::duration or any other type that exposes such an interface.

    "},{"location":"users_guide/framework_basics/quantity_arithmetics/#other-maths","title":"Other maths","text":"

    This chapter scopes only on the quantity type's operators. However, there are many named math functions taking quantities as arguments. Those can be found in the mp-units/math.h header file. Among others, we can find there the following:

    In the library, we can also find mp-units/random.h header file with all the pseudo-random number generators working on quantity types.

    "},{"location":"users_guide/framework_basics/simple_and_typed_quantities/","title":"Simple and Typed Quantities","text":"

    ISO defines a quantity as:

    Quote

    property of a phenomenon, body, or substance, where the property has a magnitude that can be expressed as a number and a reference

    After that, it says:

    Quote

    A reference can be a measurement unit, a measurement procedure, a reference material, or a combination of such.

    "},{"location":"users_guide/framework_basics/simple_and_typed_quantities/#quantity-class-template","title":"quantity class template","text":"

    In the mp-units library, a quantity is represented with the following class template:

    template<Reference auto R,\n         RepresentationOf<get_quantity_spec(R)> Rep = double>\nclass quantity;\n

    The concept Reference is satisfied by a type that provides all the domain-specific metadata describing a quantity (besides the representation type and its value). Such a type can be either:

    Important

    All units in the SI system have an associated quantity type.

    A reference type is implicitly created as a result of the following expression:

    constexpr auto ref = isq::length[m];\n

    The above example results in the following type reference<isq::length(), si::metre()> being instantiated.

    As we have two alternative options that satisfy the Reference concept in the mp-units library, we also have two modes of dealing with quantities.

    "},{"location":"users_guide/framework_basics/simple_and_typed_quantities/#simple-quantities","title":"Simple quantities","text":"

    The simple mode might be preferred by many developers. It is all about units. Quantities using this mode have shorter type identifiers, resulting in easier-to-understand error messages and better debugging experience.

    Here is a simple example showing how to deal with such quantities:

    C++ modulesHeader files 
    #include <print>\nimport mp_units;\n\nusing namespace mp_units;\n\nconstexpr quantity<si::metre / si::second> avg_speed(quantity<si::metre> dist,\n                                                     quantity<si::second> time)\n{\n  return dist / time;\n}\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n\n  const quantity distance = 110 * km;\n  const quantity duration = 2 * h;\n  const quantity speed = avg_speed(distance, duration);\n\n  std::println(\"A car driving {} in {} has an average speed of {::N[.4]} ({::N[.4]})\",\n               distance, duration, speed, speed.in(km / h));\n}\n
    #include <mp-units/systems/si.h>\n#include <print>\n\nusing namespace mp_units;\n\nconstexpr quantity<si::metre / si::second> avg_speed(quantity<si::metre> dist,\n                                                     quantity<si::second> time)\n{\n  return dist / time;\n}\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n\n  const quantity distance = 110 * km;\n  const quantity duration = 2 * h;\n  const quantity speed = avg_speed(distance, duration);\n\n  std::println(\"A car driving {} in {} has an average speed of {::N[.4]} ({::N[.4]})\",\n               distance, duration, speed, speed.in(km / h));\n}\n

    The code above prints:

    A car driving 110 km in 2 h has an average speed of 15.28 m/s (55 km/h)\n

    Try it on Compiler Explorer

    "},{"location":"users_guide/framework_basics/simple_and_typed_quantities/#user-provided-unit-wrappers","title":"User-provided unit wrappers","text":"

    Sometimes it might be awkward to type some derived units:

    quantity speed = 60 * km / h;\n

    In case such a unit is used a lot in the project, a user can easily provide a nicely named wrapper for it with:

    constexpr auto kmph = km / h;\nquantity speed = 60 * kmph;\n
    "},{"location":"users_guide/framework_basics/simple_and_typed_quantities/#easy-to-understand-compilation-error-messages","title":"Easy-to-understand compilation error messages","text":"

    In case a user makes an error in a quantity equation and the result of the calculation will not match the function return type, the compiler will detect such an issue at compile-time.

    For example, in case we will make the following error:

    constexpr quantity<si::metre / si::second> avg_speed(quantity<si::metre> dist,\n                                                     quantity<si::second> time)\n{\n  return dist * time;  // (1)!\n}\n
    1. Quantities multiplied (instead of divided) by accident.

    the following compilation error message will be provided:

    error: no viable conversion from returned value of type\n       'quantity<mp_units::derived_unit<mp_units::si::metre, mp_units::si::second>{{{}}}, [...]>'\n       to function return type\n       'quantity<mp_units::derived_unit<mp_units::si::metre, mp_units::per<mp_units::si::second>>{{{}}}, [...]>'\n   10 |   return dist * time;\n      |          ^~~~~~~~~~~\n
    "},{"location":"users_guide/framework_basics/simple_and_typed_quantities/#typed-quantities","title":"Typed quantities","text":"

    Simple mode is all about and just about units. Typed quantities should be preferred if we also want to be quantity-safe. This, for example, allows us to specify if we deal with width, height, or radius and ensure we will not assign one to another by accident.

    The previous example can be re-typed using typed quantities in the following way:

    C++ modulesHeader files 
    #include <print>\nimport mp_units;\n\nusing namespace mp_units;\n\nconstexpr quantity<isq::speed[si::metre / si::second]> avg_speed(quantity<isq::length[si::metre]> dist,\n                                                                 quantity<isq::time[si::second]> time)\n{\n  return dist / time;\n}\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n\n  const quantity distance = isq::distance(110 * km);\n  const quantity duration = isq::time(2 * h);\n  const quantity speed = avg_speed(distance, duration);\n\n  std::println(\"A car driving {} in {} has an average speed of {::N[.4]} ({::N[.4]})\",\n               distance, duration, speed, speed.in(km / h));\n}\n
    #include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n#include <print>\n\nusing namespace mp_units;\n\nconstexpr quantity<isq::speed[si::metre / si::second]> avg_speed(quantity<isq::length[si::metre]> dist,\n                                                                 quantity<isq::time[si::second]> time)\n{\n  return dist / time;\n}\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n\n  const quantity distance = isq::distance(110 * km);\n  const quantity duration = isq::time(2 * h);\n  const quantity speed = avg_speed(distance, duration);\n\n  std::println(\"A car driving {} in {} has an average speed of {::N[.4]} ({::N[.4]})\",\n               distance, duration, speed, speed.in(km / h));\n}\n
    A car driving 110 km in 2 h has an average speed of 15.28 m/s (55 km/h)\n

    Try it on Compiler Explorer

    In case we will accidentally make the same calculation error as before, this time, we will get a bit longer error message, this time also containing information about the quantity type:

    error: no viable conversion from returned value of type\n       'quantity<reference<get_quantity_spec(metre{}) * struct time{{{}}}, metre{} * second{{}}>{}, [...]>'\n       to function return type\n       'quantity<reference<speed{}, derived_unit<metre, per<second>>{}>{}, [...]>'\n   12 |   return dist * time;\n      |          ^~~~~~~~~~~\n

    As we can see above, the compilation error is longer but still relatively easy to understand.

    "},{"location":"users_guide/framework_basics/simple_and_typed_quantities/#quantity-safety-with-typed-quantities","title":"Quantity-safety with typed quantities","text":"

    Based on the previous example, it might seem that typed quantities are not that useful, more to type and provide harder-to-understand error messages. It might be true in some cases, but there are scenarios where they offer additional level of safety.

    Let's see another example:

    C++ modulesHeader files SimpleTyped 
    #include <numbers>\nimport mp_units;\n\nusing namespace mp_units;\n\nclass StorageTank {\n  quantity<square(si::metre)> base_;\n  quantity<si::metre> height_;\npublic:\n  constexpr StorageTank(const quantity<square(si::metre)>& base,\n                        const quantity<si::metre>& height) :\n    base_(base), height_(height)\n  {\n  }\n\n  // ...\n};\n\nclass CylindricalStorageTank : public StorageTank {\npublic:\n  constexpr CylindricalStorageTank(const quantity<si::metre>& radius,\n                                   const quantity<si::metre>& height) :\n    StorageTank(std::numbers::pi * pow<2>(radius), height)\n  {\n  }\n};\n\nclass RectangularStorageTank : public StorageTank {\npublic:\n  constexpr RectangularStorageTank(const quantity<si::metre>& length,\n                                   const quantity<si::metre>& width,\n                                   const quantity<si::metre>& height) :\n    StorageTank(length * width, height)\n  {\n  }\n};\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n  auto tank = RectangularStorageTank(1'000 * mm, 500 * mm, 200 * mm);\n  // ...\n}\n
    #include <numbers>\nimport mp_units;\n\nusing namespace mp_units;\n\n// add a custom quantity type of kind isq::length\ninline constexpr struct horizontal_length final :\n    quantity_spec<isq::length> {} horizontal_length;\n\n// add a custom derived quantity type of kind isq::area\n// with a constrained quantity equation\ninline constexpr struct horizontal_area final :\n    quantity_spec<isq::area, horizontal_length * isq::width> {} horizontal_area;\n\nclass StorageTank {\n  quantity<horizontal_area[square(si::metre)]> base_;\n  quantity<isq::height[si::metre]> height_;\npublic:\n  constexpr StorageTank(const quantity<horizontal_area[square(si::metre)]>& base,\n                        const quantity<isq::height[si::metre]>& height) :\n    base_(base), height_(height)\n  {\n  }\n\n  // ...\n};\n\nclass CylindricalStorageTank : public StorageTank {\npublic:\n  constexpr CylindricalStorageTank(const quantity<isq::radius[si::metre]>& radius,\n                                   const quantity<isq::height[si::metre]>& height) :\n    StorageTank(quantity_cast<horizontal_area>(std::numbers::pi * pow<2>(radius)),\n                height)\n  {\n  }\n};\n\nclass RectangularStorageTank : public StorageTank {\npublic:\n  constexpr RectangularStorageTank(const quantity<horizontal_length[si::metre]>& length,\n                                   const quantity<isq::width[si::metre]>& width,\n                                   const quantity<isq::height[si::metre]>& height) :\n    StorageTank(length * width, height)\n  {\n  }\n};\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n  auto tank = RectangularStorageTank(horizontal_length(1'000 * mm),\n                                     isq::width(500 * mm),\n                                     isq::height(200 * mm));\n  // ...\n}\n
    SimpleTyped 
    #include <mp-units/math.h>\n#include <mp-units/systems/si.h>\n#include <numbers>\n\nusing namespace mp_units;\n\nclass StorageTank {\n  quantity<square(si::metre)> base_;\n  quantity<si::metre> height_;\npublic:\n  constexpr StorageTank(const quantity<square(si::metre)>& base,\n                        const quantity<si::metre>& height) :\n    base_(base), height_(height)\n  {\n  }\n\n  // ...\n};\n\nclass CylindricalStorageTank : public StorageTank {\npublic:\n  constexpr CylindricalStorageTank(const quantity<si::metre>& radius,\n                                   const quantity<si::metre>& height) :\n    StorageTank(std::numbers::pi * pow<2>(radius), height)\n  {\n  }\n};\n\nclass RectangularStorageTank : public StorageTank {\npublic:\n  constexpr RectangularStorageTank(const quantity<si::metre>& length,\n                                   const quantity<si::metre>& width,\n                                   const quantity<si::metre>& height) :\n    StorageTank(length * width, height)\n  {\n  }\n};\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n  auto tank = RectangularStorageTank(1'000 * mm, 500 * mm, 200 * mm);\n  // ...\n}\n
    #include <mp-units/math.h>\n#include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n#include <numbers>\n\nusing namespace mp_units;\n\n// add a custom quantity type of kind isq::length\ninline constexpr struct horizontal_length final :\n    quantity_spec<isq::length> {} horizontal_length;\n\n// add a custom derived quantity type of kind isq::area\n// with a constrained quantity equation\ninline constexpr struct horizontal_area final :\n    quantity_spec<isq::area, horizontal_length * isq::width> {} horizontal_area;\n\nclass StorageTank {\n  quantity<horizontal_area[square(si::metre)]> base_;\n  quantity<isq::height[si::metre]> height_;\npublic:\n  constexpr StorageTank(const quantity<horizontal_area[square(si::metre)]>& base,\n                        const quantity<isq::height[si::metre]>& height) :\n    base_(base), height_(height)\n  {\n  }\n\n  // ...\n};\n\nclass CylindricalStorageTank : public StorageTank {\npublic:\n  constexpr CylindricalStorageTank(const quantity<isq::radius[si::metre]>& radius,\n                                   const quantity<isq::height[si::metre]>& height) :\n    StorageTank(quantity_cast<horizontal_area>(std::numbers::pi * pow<2>(radius)),\n                height)\n  {\n  }\n};\n\nclass RectangularStorageTank : public StorageTank {\npublic:\n  constexpr RectangularStorageTank(const quantity<horizontal_length[si::metre]>& length,\n                                   const quantity<isq::width[si::metre]>& width,\n                                   const quantity<isq::height[si::metre]>& height) :\n    StorageTank(length * width, height)\n  {\n  }\n};\n\nint main()\n{\n  using namespace mp_units::si::unit_symbols;\n  auto tank = RectangularStorageTank(horizontal_length(1'000 * mm),\n                                     isq::width(500 * mm),\n                                     isq::height(200 * mm));\n  // ...\n}\n

    In the above example, the highlighted call doesn't look that safe anymore in the case of simple quantities, right? Suppose someone, either by mistake or due to some refactoring, will call the function with an invalid order of arguments. In that case, the program will compile fine but not work as expected.

    Let's see what will happen if we reorder the arguments in the case of typed quantities:

    auto tank = RectangularStorageTank(horizontal_length(1'000 * mm),\n                                   isq::height(200 * mm),\n                                   isq::width(500 * mm));\n

    This time, a compiler provides the following compilation error:

    <source>:53:15: error: no matching constructor for initialization of 'RectangularStorageTank'\n   53 |   auto tank = RectangularStorageTank(horizontal_length(1'000 * mm),\n      |               ^                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n   54 |                                      isq::height(200 * mm),\n      |                                      ~~~~~~~~~~~~~~~~~~~~~~\n   55 |                                      isq::width(500 * mm));\n      |                                      ~~~~~~~~~~~~~~~~~~~~\n<source>:43:13: note: candidate constructor not viable: no known conversion from\n                'quantity<mp_units::reference<mp_units::isq::height{{{{{}}}}},\n                                              mp_units::si::milli_<mp_units::si::metre{{}}>{{{{}}}}>{}, int>' to\n                'const quantity<reference<width{}, metre{}>{}, (default) double>' for 2nd argument\n   43 |   constexpr RectangularStorageTank(const quantity<horizontal_length[m]>& length,\n      |             ^\n   44 |                                    const quantity<isq::width[m]>& width,\n      |                                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n

    What about derived quantities? In the above example, you probably noticed that we also defined a custom horizontal_area quantity of kind isq::area. This quantity has the unique property of being implicitly constructible only from the result of the multiplication of quantities of horizontal_area and isq::width or the ones that implicitly convert to them.

    Based on the above error message, we already know that a quantity of isq::height is not implicitly constructible to the quantity of isq::width. This property is transitively passed to derived quantities using them. If by accident, we will try to create a StorageTank base class in the following way:

    class RectangularStorageTank : public StorageTank {\npublic:\n  constexpr RectangularStorageTank(const quantity<horizontal_length[m]>& length,\n                                   const quantity<isq::width[m]>& width,\n                                   const quantity<isq::height[m]>& height) :\n    StorageTank(length * height, height)\n  {\n  }\n};\n

    we will again get a compilation error message like this one:

    error: no matching constructor for initialization of 'StorageTank'\n   46 |     StorageTank(length * height, height)\n      |     ^           ~~~~~~~~~~~~~~~~~~~~~~~\n<source>:22:13: note: candidate constructor not viable: no known conversion from\n                'quantity<mp_units::reference<mp_units::derived_quantity_spec<horizontal_length, mp_units::isq::height>{{}, {{}}},\n                                              mp_units::derived_unit<mp_units::power<mp_units::si::metre, 2>>{{{}}}>{}, [...]>' to\n                'const quantity<reference<horizontal_area{}, derived_unit<power<metre, 2>>{}>{}, [...]>' for 1st argument\n   22 |   constexpr StorageTank(const quantity<horizontal_area[m2]>& base,\n      |             ^           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n

    Tip

    If you need to use various quantities of the same kind, consider using typed quantities to bring an additional level of safety to your project.

    "},{"location":"users_guide/framework_basics/simple_and_typed_quantities/#quantity_cast-to-force-unsafe-conversions","title":"quantity_cast() to force unsafe conversions","text":"

    Did you notice the quantity_cast() usage in the other child class?

    class CylindricalStorageTank : public StorageTank {\npublic:\n  constexpr CylindricalStorageTank(const quantity<isq::radius[m]>& radius,\n                                   const quantity<isq::height[m]>& height) :\n    StorageTank(quantity_cast<horizontal_area>(std::numbers::pi * pow<2>(radius)),\n                height)\n  {\n  }\n};\n

    As isq::radius is not convertible to horizontal_length, the derived quantity of pow<2>(radius) can't be converted to horizontal_area as well. It would be unsafe to allow such a conversion as not all of the circles lie flat on the ground, right?

    In such a case, the user has to explicitly force such an unsafe conversion with the help of a quantity_cast(). This function name is easy to spot in code reviews or while searching the project for problems if something goes sideways. In case of unexpected quantities-related issues, this should be the first function to look for.

    Tip

    Do not overuse quantity_cast(). Use it only when necessary and ensure that the requested conversion is exactly what you need in this case.

    "},{"location":"users_guide/framework_basics/simple_and_typed_quantities/#which-mode-should-i-use-in-my-project","title":"Which mode should I use in my project?","text":"

    We have good news for you if you wonder which mode you should choose for your project. Simple and typed quantity modes can be freely mixed with each other. When you use different quantities of the same kind (e.g., radius, wavelength, altitude, ...), you should probably reach for typed quantities to bring additional safety for those cases. Otherwise, just use simple mode for the remaining quantities. The mp-units library will do its best to protect your project based on the information provided.

    Tip

    You can easily mix simple and typed quantities in your project.

    "},{"location":"users_guide/framework_basics/systems_of_quantities/","title":"Systems of Quantities","text":"

    The physical units libraries on the market typically only scope on modeling one or more systems of units. However, this is not the only system kind to model. Another, and maybe even more important, system kind is a system of quantities.

    Info

    Please note that the mp-units is probably the first library on the Open Source market (in any programming language) that models the ISQ with all its definitions provided in ISO 80000. Please provide feedback if something looks odd or could be improved.

    "},{"location":"users_guide/framework_basics/systems_of_quantities/#dimension-is-not-enough-to-describe-a-quantity","title":"Dimension is not enough to describe a quantity","text":"

    Most of the products on the market are aware of physical dimensions. However, a dimension is not enough to describe a quantity. For example, let's see the following implementation:

    class Box {\n  area base_;\n  length height_;\npublic:\n  Box(length l, length w, length h) : base_(l * w), height_(h) {}\n  // ...\n};\n\nBox my_box(2 * m, 3 * m, 1 * m);\n

    How do you like such an interface? It turns out that in most existing strongly-typed libraries this is often the best we can do

    Another typical question many users ask is how to deal with work and torque. Both of those have the same dimension but are different quantities.

    A similar issue is related to figuring out what should be the result of:

    auto res = 1 * Hz + 1 * Bq + 1 * Bd;\n

    where:

    All of those quantities have the same dimension, namely \\(\\mathsf{T}^{-1}\\), but probably it is not wise to allow adding, subtracting, or comparing them, as they describe vastly different physical properties.

    If the above example seems too abstract, let's consider a fuel consumption (fuel volume divided by distance, e.g., 6.7 l/km) and an area. Again, both have the same dimension \\(\\mathsf{L}^{2}\\), but probably it wouldn't be wise to allow adding, subtracting, or comparing a fuel consumption of a car and the area of a football field. Such an operation does not have any physical sense and should fail to compile.

    Important

    More than one quantity may be defined for the same dimension:

    It turns out that the above issues can't be solved correctly without proper modeling of a system of quantities.

    "},{"location":"users_guide/framework_basics/systems_of_quantities/#quantities-of-the-same-kind","title":"Quantities of the same kind","text":"

    ISO 80000-1

    The above quotes from ISO 80000 provide answers to all the issues above. Two quantities can't be added, subtracted, or compared unless they belong to the same kind. As frequency, activity, and modulation rate are of different kinds, the expression provided above should not compile.

    "},{"location":"users_guide/framework_basics/systems_of_quantities/#system-of-quantities-is-not-only-about-kinds","title":"System of quantities is not only about kinds","text":"

    ISO 80000 specify hundreds of different quantities. There are plenty of different kinds provided and often each kind contains more than one quantity. In fact, it turns out that such quantities form a hierarchy of quantities of the same kind.

    For example, here are all quantities of the kind length provided in the ISO 80000:

    flowchart TD\n    length[\"<b>length</b><br>[m]\"]\n    length --- width[\"<b>width</b> / <b>breadth</b>\"]\n    length --- height[\"<b>height</b> / <b>depth</b> / <b>altitude</b>\"]\n    width --- thickness[\"<b>thickness</b>\"]\n    width --- diameter[\"<b>diameter</b>\"]\n    width --- radius[\"<b>radius</b>\"]\n    length --- path_length[\"<b>path_length</b>\"]\n    path_length --- distance[\"<b>distance</b>\"]\n    distance --- radial_distance[\"<b>radial_distance</b>\"]\n    length --- wavelength[\"<b>wavelength</b>\"]\n    length --- displacement[\"<b>displacement</b><br>{vector}\"]\n    displacement --- position_vector[\"<b>position_vector</b>\"]\n    radius --- radius_of_curvature[\"<b>radius_of_curvature</b>\"]

    Each of the above quantities expresses some kind of length, and each can be measured with si::metre. However, each of them has different properties, usage, and sometimes even requires a different representation type (notice that position_vector and displacement are vector quantities).

    Forming such a hierarchy helps us in defining arithmetics and conversion rules for various quantities of the same kind.

    "},{"location":"users_guide/framework_basics/systems_of_quantities/#defining-quantities","title":"Defining quantities","text":"

    In the mp-units library all the information about the quantity is provided with the quantity_spec class template. In order to define a specific quantity a user should inherit a strong type from such an instantiation.

    Tip

    Quantity specification definitions benefit from an explicit object parameter added in C++23 to remove the need for CRTP idiom, which significantly simplifies the code. However, as C++23 is far from being mainstream today, a portability macro QUANTITY_SPEC() is provided and used consistently through the library to allow the code to compile with C++20 compilers, thanks to the CRTP usage under the hood.

    See more in the C++ compiler support chapter.

    For example, here is how the above quantity kind tree can be modeled in the library:

    C++23C++20Portable 
    inline constexpr struct length final : quantity_spec<dim_length> {} length;\ninline constexpr struct width final : quantity_spec<length> {} width;\ninline constexpr auto breadth = width;\ninline constexpr struct height final : quantity_spec<length> {} height;\ninline constexpr auto depth = height;\ninline constexpr auto altitude = height;\ninline constexpr struct thickness final : quantity_spec<width> {} thickness;\ninline constexpr struct diameter final : quantity_spec<width> {} diameter;\ninline constexpr struct radius final : quantity_spec<width> {} radius;\ninline constexpr struct radius_of_curvature final : quantity_spec<radius> {} radius_of_curvature;\ninline constexpr struct path_length final : quantity_spec<length> {} path_length;\ninline constexpr auto arc_length = path_length;\ninline constexpr struct distance final : quantity_spec<path_length> {} distance;\ninline constexpr struct radial_distance final : quantity_spec<distance> {} radial_distance;\ninline constexpr struct wavelength final : quantity_spec<length> {} wavelength;\ninline constexpr struct displacement final : quantity_spec<length, quantity_character::vector> {} displacement;\ninline constexpr struct position_vector final : quantity_spec<displacement> {} position_vector;\n
    inline constexpr struct length final : quantity_spec<length, dim_length> {} length;\ninline constexpr struct width final : quantity_spec<width, length> {} width;\ninline constexpr auto breadth = width;\ninline constexpr struct height final : quantity_spec<height, length> {} height;\ninline constexpr auto depth = height;\ninline constexpr auto altitude = height;\ninline constexpr struct thickness final : quantity_spec<thickness, width> {} thickness;\ninline constexpr struct diameter final : quantity_spec<diameter, width> {} diameter;\ninline constexpr struct radius final : quantity_spec<radius, width> {} radius;\ninline constexpr struct radius_of_curvature final : quantity_spec<radius_of_curvature, radius> {} radius_of_curvature;\ninline constexpr struct path_length final : quantity_spec<path_length, length> {} path_length;\ninline constexpr auto arc_length = path_length;\ninline constexpr struct distance final : quantity_spec<distance, path_length> {} distance;\ninline constexpr struct radial_distance final : quantity_spec<radial_distance, distance> {} radial_distance;\ninline constexpr struct wavelength final : quantity_spec<wavelength, length> {} wavelength;\ninline constexpr struct displacement final : quantity_spec<displacement, length, quantity_character::vector> {} displacement;\ninline constexpr struct position_vector final : quantity_spec<position_vector, displacement> {} position_vector;\n
    QUANTITY_SPEC(length, dim_length);\nQUANTITY_SPEC(width, length);\ninline constexpr auto breadth = width;\nQUANTITY_SPEC(height, length);\ninline constexpr auto depth = height;\ninline constexpr auto altitude = height;\nQUANTITY_SPEC(thickness, width);\nQUANTITY_SPEC(diameter, width);\nQUANTITY_SPEC(radius, width);\nQUANTITY_SPEC(radius_of_curvature, radius);\nQUANTITY_SPEC(path_length, length);\ninline constexpr auto arc_length = path_length;\nQUANTITY_SPEC(distance, path_length);\nQUANTITY_SPEC(radial_distance, distance);\nQUANTITY_SPEC(wavelength, length);\nQUANTITY_SPEC(displacement, length, quantity_character::vector);\nQUANTITY_SPEC(position_vector, displacement);\n

    Note

    More information on how to define a system of quantities can be found in the \"International System of Quantities (ISQ)\" chapter.

    "},{"location":"users_guide/framework_basics/systems_of_quantities/#comparing-adding-and-subtracting-quantities","title":"Comparing, adding, and subtracting quantities","text":"

    ISO 80000 explicitly states that width and height are quantities of the same kind, and as such they:

    If we take the above for granted, the only reasonable result of 1 * width + 1 * height is 2 * length, where the result of length is known as a common quantity type. A result of such an equation is always the first common node in a hierarchy tree of the same kind. For example:

    static_assert(get_common_quantity_spec(isq::width, isq::height) == isq::length);\nstatic_assert(get_common_quantity_spec(isq::thickness, isq::radius) == isq::width);\nstatic_assert(get_common_quantity_spec(isq::distance, isq::path_length) == isq::path_length);\n
    "},{"location":"users_guide/framework_basics/systems_of_quantities/#converting-between-quantities","title":"Converting between quantities","text":"

    Based on the same hierarchy of quantities of kind length, we can define quantity conversion rules.

    1. Implicit conversions

      • every width is a length
      • every radius is a width
      static_assert(implicitly_convertible(isq::width, isq::length));\nstatic_assert(implicitly_convertible(isq::radius, isq::width));\nstatic_assert(implicitly_convertible(isq::radius, isq::length));\n

      Implicit conversions are allowed on copy-initialization:

      void foo(quantity<isq::length[m]> q);\n
      quantity<isq::width[m]> q1 = 42 * m;\nquantity<isq::length[m]> q2 = q1;  // implicit quantity conversion\nfoo(q1);                           // implicit quantity conversion\n

    2. Explicit conversions

      • not every length is a width
      • not every width is a radius
      static_assert(!implicitly_convertible(isq::length, isq::width));\nstatic_assert(!implicitly_convertible(isq::width, isq::radius));\nstatic_assert(!implicitly_convertible(isq::length, isq::radius));\nstatic_assert(explicitly_convertible(isq::length, isq::width));\nstatic_assert(explicitly_convertible(isq::width, isq::radius));\nstatic_assert(explicitly_convertible(isq::length, isq::radius));\n

      Explicit conversions are forced by passing the quantity to a call operator of a quantity_spec type or by calling quantity's explicit constructor:

      void foo(quantity<isq::height[m]> q);\n
      quantity<isq::length[m]> q1 = 42 * m;\nquantity<isq::height[m]> q2 = isq::height(q1);  // explicit quantity conversion\nquantity<isq::height[m]> q3(q1);                // direct initialization\nfoo(isq::height(q1));                           // explicit quantity conversion\n

    3. Explicit casts

      • height is not a width
      • both height and width are quantities of kind length
      static_assert(!implicitly_convertible(isq::height, isq::width));\nstatic_assert(!explicitly_convertible(isq::height, isq::width));\nstatic_assert(castable(isq::height, isq::width));\n

      Explicit casts are forced with a dedicated quantity_cast function:

      void foo(quantity<isq::height[m]> q);\n
      quantity<isq::width[m]> q1 = 42 * m;\nquantity<isq::height[m]> q2 = quantity_cast<isq::height>(q1);  // explicit quantity cast\nfoo(quantity_cast<isq::height>(q1));                           // explicit quantity cast\n

    4. No conversion

      • time has nothing in common with length
      static_assert(!implicitly_convertible(isq::time, isq::length));\nstatic_assert(!explicitly_convertible(isq::time, isq::length));\nstatic_assert(!castable(isq::time, isq::length));\n

      Even the explicit casts will not force such a conversion:

      void foo(quantity<isq::length[m]>);\n
      quantity<isq::length[m]> q1 = 42 * s;    // Compile-time error\nfoo(quantity_cast<isq::length>(42 * s)); // Compile-time error\n
    "},{"location":"users_guide/framework_basics/systems_of_quantities/#hierarchies-of-derived-quantities","title":"Hierarchies of derived quantities","text":"

    Derived quantity equations often do not automatically form a hierarchy tree. This is why it is sometimes not obvious what such a tree should look like. Also, ISO explicitly states:

    ISO/IEC Guide 99

    The division of \u2018quantity\u2019 according to \u2018kind of quantity\u2019 is, to some extent, arbitrary.

    The below presents some arbitrary hierarchy of derived quantities of kind energy:

    flowchart TD\n    energy[\"<b>energy</b><br><i>(mass * length<sup>2</sup> / time<sup>2</sup>)</i><br>[J]\"]\n    energy --- mechanical_energy[\"<b>mechanical_energy</b>\"]\n    mechanical_energy --- potential_energy[\"<b>potential_energy</b>\"]\n    potential_energy --- gravitational_potential_energy[\"<b>gravitational_potential_energy</b><br><i>(mass * acceleration_of_free_fall * height)</i>\"]\n    potential_energy --- elastic_potential_energy[\"<b>elastic_potential_energy</b><br><i>(spring_constant * amount_of_compression<sup>2</sup>)</i>\"]\n    mechanical_energy --- kinetic_energy[\"<b>kinetic_energy</b><br><i>(mass * speed<sup>2</sup>)</i>\"]\n    energy --- enthalpy[\"<b>enthalpy</b>\"]\n    enthalpy --- internal_energy[\"<b>internal_energy</b> / <b>thermodynamic_energy</b>\"]\n    internal_energy --- Helmholtz_energy[\"<b>Helmholtz_energy</b> / <b>Helmholtz_function</b>\"]\n    enthalpy --- Gibbs_energy[\"<b>Gibbs_energy</b> / <b>Gibbs_function</b>\"]\n    energy --- active_energy[\"<b>active_energy</b>\"]

    Notice, that even though all of those quantities have the same dimension and can be expressed in the same units, they have different quantity equations that can be used to create them implicitly:

    "},{"location":"users_guide/framework_basics/systems_of_quantities/#modeling-a-quantity-kind","title":"Modeling a quantity kind","text":"

    In the physical units library, we also need an abstraction describing an entire family of quantities of the same kind. Such quantities have not only the same dimension but also can be expressed in the same units.

    To annotate a quantity to represent its kind (and not just a hierarchy tree's root quantity) we introduced a kind_of<> specifier. For example, to express any quantity of length, we need to type kind_of<isq::length>.

    Important

    isq::length and kind_of<isq::length> are two different things.

    Such an entity behaves as any quantity of its kind. This means that it is implicitly convertible to any quantity in a tree.

    static_assert(!implicitly_convertible(isq::length, isq::height));\nstatic_assert(implicitly_convertible(kind_of<isq::length>, isq::height));\n

    Additionally, the result of operations on quantity kinds is also a quantity kind:

    static_assert(same_type<kind_of<isq::length> / kind_of<isq::time>, kind_of<isq::length / isq::time>>);\n

    However, if at least one equation's operand is not a quantity kind, the result becomes a \"strong\" quantity where all the kinds are converted to the hierarchy tree's root quantities:

    static_assert(!same_type<kind_of<isq::length> / isq::time, kind_of<isq::length / isq::time>>);\nstatic_assert(same_type<kind_of<isq::length> / isq::time, isq::length / isq::time>);\n

    Info

    Only a root quantity from the hierarchy tree or the one marked with is_kind specifier in the quantity_spec definition can be put as a template parameter to the kind_of specifier. For example, kind_of<isq::width> will fail to compile. However, we can call get_kind(q) to obtain a kind of any quantity:

    static_assert(get_kind(isq::width) == kind_of<isq::length>);\n
    "},{"location":"users_guide/framework_basics/systems_of_units/","title":"Systems of Units","text":"

    Modeling a system of units is probably the most important feature and a selling point of every physical units library. Thanks to that, the library can protect users from performing invalid operations on quantities and provide automated conversion factors between various compatible units.

    Probably all the libraries in the wild model the SI and many of them provide support for additional units belonging to various other systems (e.g., imperial, cgs, etc).

    "},{"location":"users_guide/framework_basics/systems_of_units/#systems-of-units-are-based-on-systems-of-quantities","title":"Systems of Units are based on Systems of Quantities","text":"

    Systems of quantities specify a set of quantities and equations relating to those quantities. Those equations do not take any unit or a numerical representation into account at all. To create a quantity, we need to add those missing pieces of information. This is where a system of units kicks in.

    The SI is explicitly stated to be based on the ISQ. Among others, it defines 7 base units, one for each base quantity. In the mp-units this is expressed by associating a quantity kind (that we discussed in detail in the previous chapter) with a unit that is used to express it:

    inline constexpr struct metre final : named_unit<\"m\", kind_of<isq::length>> {} metre;\n

    Important

    The kind_of<isq::length> above states explicitly that this unit has an associated quantity kind. In other words, si::metre (and scaled units based on it) can be used to express the amount of any quantity of kind length.

    "},{"location":"users_guide/framework_basics/systems_of_units/#units-compose","title":"Units compose","text":"

    One of the most vital points of the SI system is that its units compose. This allows providing thousands of different units for hundreds of various quantities with a tiny set of predefined units and prefixes.

    The same is modeled in the mp-units library, which also allows composing predefined units to create a nearly infinite number of different derived units. For example, one can write:

    quantity<si::metre / si::second> q;\n

    to express a quantity of speed. The resulting quantity type is implicitly inferred from the unit equation by repeating the same operations on the associated quantity kinds.

    "},{"location":"users_guide/framework_basics/systems_of_units/#many-shades-of-the-same-unit","title":"Many shades of the same unit","text":"

    The SI provides the names for 22 common coherent units of 22 derived quantities.

    Each such named derived unit is a result of a specific predefined unit equation. For example, a unit of power quantity is defined in the library as:

    inline constexpr struct watt final : named_unit<\"W\", joule / second> {} watt;\n

    However, a power quantity can be expressed in other units as well. For example, the following:

    auto q1 = 42 * W;\nstd::cout << q1 << \"\\n\";\nstd::cout << q1.in(J / s) << \"\\n\";\nstd::cout << q1.in(N * m / s) << \"\\n\";\nstd::cout << q1.in(kg * m2 / s3) << \"\\n\";\n

    prints:

    42 W\n42 J/s\n42 N m/s\n42 kg m\u00b2/s\u00b3\n

    All of the above quantities are equivalent and mean exactly the same.

    Note

    The above code example may give the impression that the order of components in a derived unit is determined by the multiplication order. This is not the case. As stated in Simplifying the resulting symbolic expressions, to be able to reason about and simplify units, the library needs to order them in an appropriate order. This will affect the order of components in a resulting type and text output.

    Please refer to our FAQ for more information.

    "},{"location":"users_guide/framework_basics/systems_of_units/#constraining-a-derived-unit-to-work-only-with-a-specific-derived-quantity","title":"Constraining a derived unit to work only with a specific derived quantity","text":"

    Some derived units are valid only for specific derived quantities. For example, SI specifies both hertz and becquerel derived units with the same unit equation 1 / s. However, it also explicitly states:

    SI Brochure

    The hertz shall only be used for periodic phenomena and the becquerel shall only be used for stochastic processes in activity referred to a radionuclide.

    The above means that the usage of becquerel as a unit of a frequency quantity is an error.

    The library allows constraining such units to work only with quantities of a specific kind in the following way:

    inline constexpr struct hertz final : named_unit<\"Hz\", one / second, kind_of<isq::frequency>> {} hertz;\ninline constexpr struct becquerel final : named_unit<\"Bq\", one / second, kind_of<isq::activity>> {} becquerel;\n

    With the above, hertz can only be used with frequencies, while becquerel should only be used with quantities of activity. This means that the following equation will not compile:

    auto q = 1 * Hz + 1 * Bq;   // Fails to compile\n

    This is exactly what we wanted to achieve to improve the type-safety of the library.

    "},{"location":"users_guide/framework_basics/systems_of_units/#prefixed-units","title":"Prefixed units","text":"

    Besides named units, the SI specifies also 24 prefixes (all being a power of 10) that can be prepended to all named units to obtain various scaled versions of them.

    Implementation of std::ratio provided by all major compilers is able to express only 16 of them. This is why, in the mp-units, we had to find an alternative way to represent unit magnitude in a more flexible way.

    Each prefix is implemented similarly to the following:

    template<PrefixableUnit U> struct quecto_ : prefixed_unit<\"q\", mag_power<10, -30>, U{}> {};\ntemplate<PrefixableUnit auto U> constexpr quecto_<decltype(U)> quecto;\n

    and then a PrefixableUnit can be prefixed in the following way:

    inline constexpr auto qm = quecto<metre>;\n

    The usage of mag_power not only enables providing support for SI prefixes, but it can also efficiently represent any rational magnitude. For example, IEC 80000 prefixes used in the IT industry can be implemented as:

    template<PrefixableUnit U> struct yobi_ : prefixed_unit<\"Yi\", mag_power<2, 80>, U{}> {};\ntemplate<PrefixableUnit auto U> constexpr yobi_<decltype(U)> yobi;\n
    "},{"location":"users_guide/framework_basics/systems_of_units/#scaled-units","title":"Scaled units","text":"

    In the SI, all units are either base or derived units or prefixed versions of those. However, those are only some of the options possible.

    For example, there is a list of off-system units accepted for use with SI. Those are scaled versions of the SI units with ratios that can't be explicitly expressed with predefined SI prefixes. Those include units like minute, hour, or electronvolt:

    inline constexpr struct minute final : named_unit<\"min\", mag<60> * si::second> {} minute;\ninline constexpr struct hour final : named_unit<\"h\", mag<60> * minute> {} hour;\ninline constexpr struct electronvolt final : named_unit<\"eV\", mag_ratio<1'602'176'634, 1'000'000'000> * mag_power<10, -19> * si::joule> {} electronvolt;\n

    Also, units of other systems of units are often defined in terms of scaled versions of the SI units. For example, the international yard is defined as:

    inline constexpr struct yard final : named_unit<\"yd\", mag_ratio<9'144, 10'000> * si::metre> {} yard;\n

    For some units, a magnitude might also be irrational. The best example here is a degree which is defined using a floating-point magnitude having a factor of the number \u03c0 (Pi):

    inline constexpr struct pi final : mag_constant<symbol_text{u8\"\u03c0\", \"pi\"}, std::numbers::pi_v<long double>> {} pi;\ninline constexpr auto \u03c0 = pi;\n
    inline constexpr struct degree final : named_unit<{u8\"\u00b0\", \"deg\"}, mag<\u03c0> / mag<180> * si::radian> {} degree;\n
    "},{"location":"users_guide/framework_basics/systems_of_units/#unit-symbols","title":"Unit symbols","text":"

    Units are available via their full names or through their short symbols. To use a long version, it is enough to type:

    quantity q1 = 42 * si::metre / si::second;\nquantity q2 = 42 * si::kilo<si::metre> / si::hour;\n

    To simplify how we spell it a short, user-friendly symbols are provided in a dedicated subnamespace in systems definitions:

    namespace si::unit_symbols {\n\nconstexpr auto m = si::metre;\nconstexpr auto km = si::kilo<si::metre>;\nconstexpr auto s = si::second;\nconstexpr auto h = si::hour;\n\n}\n

    Unit symbols introduce a lot of short identifiers into the current namespace. This is why they are opt-in. A user has to explicitly \"import\" them from a dedicated unit_symbols namespace:

    using-declarationusing-directive 
    using namespace si::unit_symbols;\n\nquantity q1 = 42 * m / s;\nquantity q2 = 42 * km / h;\n
    using si::unit_symbols::m;\nusing si::unit_symbols::km;\nusing si::unit_symbols::s;\nusing si::unit_symbols::h;\n\nquantity q1 = 42 * m / s;\nquantity q2 = 42 * km / h;\n

    We also provide alternative object identifiers using UTF-8 characters in their names for most unit symbols. The code using UTF-8 looks nicer, but it is harder to type on the keyboard. This is why we provide both versions of identifiers for such units.

    PortableWith UTF-8 glyphs 
    quantity resistance = 60 * kohm;\nquantity capacitance = 100 * uF;\n
    quantity resistance = 60 * k\u03a9;\nquantity capacitance = 100 * \u00b5F;\n
    "},{"location":"users_guide/framework_basics/systems_of_units/#common-units","title":"Common units","text":"

    Adding, subtracting, or comparing two quantities of different units will force the library to find a common unit for those. This is to prevent data truncation. For the cases when one of the units is an integral multiple of the another, the resulting quantity will use a \"smaller\" one in its result. For example:

    static_assert((1 * kg + 1 * g).unit == g);\nstatic_assert((1 * km + 1 * mm).unit == mm);\nstatic_assert((1 * yd + 1 * mi).unit == yd);\n

    However, in many cases an arithmetic operation on quantities of different units will result in a yet another unit. This happens when none of the source units is an integral multiple of another. In such cases, the library returns a special type that denotes that we are dealing with a common unit of such an equation:

    quantity q1 = 1 * km + 1 * mi;     // quantity<common_unit<international::mile, si::kilo_<si::metre>>{}, int>\nquantity q2 = 1. * rad + 1. * deg; // quantity<common_unit<si::degree, si::radian>{}, double>\n

    Note

    A user should never explicitly instantiate a common_unit class template. The library's framework will do it based on the provided quantity equation.

    "},{"location":"users_guide/framework_basics/text_output/","title":"Text Output","text":"

    Besides providing dimensional analysis and unit conversions, the library also tries hard to print any quantity in the most user-friendly way. We can print the entire quantity or its selected parts (numerical value, unit, or dimension).

    Note

    The library does not provide a text output for quantity points. The quantity stored inside is just an implementation detail of this type. It is a vector from a specific origin. Without the knowledge of the origin, the vector by itself is useless as we can't determine which point it describes.

    In the current library design, point origin does not provide any text in its definition. Even if we could add such information to the point's definition, we would not know how to output it in the text. There may be many ways to do it. For example, should we prepend or append the origin part to the quantity text?

    For example, the text output of 42 m for a quantity point may mean many things. It may be an offset from the mountain top, sea level, or maybe the center of Mars. Printing 42 m AMSL for altitudes above mean sea level is a much better solution, but the library does not have enough information to print it that way by itself.

    Please let us know if you have a good idea of how to solve this issue.

    "},{"location":"users_guide/framework_basics/text_output/#predefined-symbols","title":"Predefined symbols","text":"

    The definitions of dimensions, units, prefixes, and constants require assigning text symbols for each entity. Those symbols will be composed by the library's framework to express dimensions and units of derived quantities.

    DimensionsUnitsPrefixesConstants 
    inline constexpr struct dim_length final : base_dimension<\"L\"> {} dim_length;\ninline constexpr struct dim_mass final : base_dimension<\"M\"> {} dim_mass;\ninline constexpr struct dim_time final : base_dimension<\"T\"> {} dim_time;\ninline constexpr struct dim_electric_current final : base_dimension<\"I\"> {} dim_electric_current;\ninline constexpr struct dim_thermodynamic_temperature final : base_dimension<{u8\"\u0398\", \"O\"}> {} dim_thermodynamic_temperature;\ninline constexpr struct dim_amount_of_substance final : base_dimension<\"N\"> {} dim_amount_of_substance;\ninline constexpr struct dim_luminous_intensity final : base_dimension<\"J\"> {} dim_luminous_intensity;\n
    inline constexpr struct second final : named_unit<\"s\", kind_of<isq::time>> {} second;\ninline constexpr struct metre final : named_unit<\"m\", kind_of<isq::length>> {} metre;\ninline constexpr struct gram final : named_unit<\"g\", kind_of<isq::mass>> {} gram;\ninline constexpr auto kilogram = kilo<gram>;\n\ninline constexpr struct newton final : named_unit<\"N\", kilogram * metre / square(second)> {} newton;\ninline constexpr struct joule final : named_unit<\"J\", newton * metre> {} joule;\ninline constexpr struct watt final : named_unit<\"W\", joule / second> {} watt;\ninline constexpr struct coulomb final : named_unit<\"C\", ampere * second> {} coulomb;\ninline constexpr struct volt final : named_unit<\"V\", watt / ampere> {} volt;\ninline constexpr struct farad final : named_unit<\"F\", coulomb / volt> {} farad;\ninline constexpr struct ohm final : named_unit<{u8\"\u03a9\", \"ohm\"}, volt / ampere> {} ohm;\n
    template<PrefixableUnit U> struct micro_ : prefixed_unit<{u8\"\u00b5\", \"u\"}, mag_power<10, -6>, U{}> {};\ntemplate<PrefixableUnit U> struct milli_ : prefixed_unit<\"m\", mag_power<10, -3>, U{}> {};\ntemplate<PrefixableUnit U> struct centi_ : prefixed_unit<\"c\", mag_power<10, -2>, U{}> {};\ntemplate<PrefixableUnit U> struct deci_  : prefixed_unit<\"d\", mag_power<10, -1>, U{}> {};\ntemplate<PrefixableUnit U> struct deca_  : prefixed_unit<\"da\", mag_power<10, 1>, U{}> {};\ntemplate<PrefixableUnit U> struct hecto_ : prefixed_unit<\"h\", mag_power<10, 2>, U{}> {};\ntemplate<PrefixableUnit U> struct kilo_  : prefixed_unit<\"k\", mag_power<10, 3>, U{}> {};\ntemplate<PrefixableUnit U> struct mega_  : prefixed_unit<\"M\", mag_power<10, 6>, U{}> {};\n
    inline constexpr struct hyperfine_structure_transition_frequency_of_cs final : named_unit<{u8\"\u0394\u03bd_Cs\", \"dv_Cs\"}, mag<9'192'631'770> * hertz> {} hyperfine_structure_transition_frequency_of_cs;\ninline constexpr struct speed_of_light_in_vacuum final : named_unit<\"c\", mag<299'792'458> * metre / second> {} speed_of_light_in_vacuum;\ninline constexpr struct planck_constant final : named_unit<\"h\", mag_ratio<662'607'015, 100'000'000> * mag_power<10, -34> * joule * second> {} planck_constant;\ninline constexpr struct elementary_charge final : named_unit<\"e\", mag_ratio<1'602'176'634, 1'000'000'000> * mag_power<10, -19> * coulomb> {} elementary_charge;\ninline constexpr struct boltzmann_constant final : named_unit<\"k\", mag_ratio<1'380'649, 1'000'000> * mag_power<10, -23> * joule / kelvin> {} boltzmann_constant;\ninline constexpr struct avogadro_constant final : named_unit<\"N_A\", mag_ratio<602'214'076, 100'000'000> * mag_power<10, 23> / mole> {} avogadro_constant;\ninline constexpr struct luminous_efficacy final : named_unit<\"K_cd\", mag<683> * lumen / watt> {} luminous_efficacy;\n

    Important

    Two symbols always have to be provided if the primary symbol contains characters outside of the basic literal character set. The first must be provided as a UTF-8 literal and may contain any Unicode characters. The second one must provide an alternative spelling and only use characters from within of basic literal character set.

    Note

    Unicode provides only a minimal set of characters available as subscripts, which are often used to differentiate various constants and quantities of the same kind. To workaround this issue, mp-units uses the '_' character to specify that the following characters should be considered a subscript of the symbol.

    Tip

    For older compilers, it might be required to specify a symbol_text class explicitly template name to initialize it with two symbols:

    inline constexpr struct ohm final : named_unit<symbol_text{u8\"\u03a9\", \"ohm\"}, volt / ampere> {} ohm;\n
    "},{"location":"users_guide/framework_basics/text_output/#symbols-for-derived-entities","title":"Symbols for derived entities","text":""},{"location":"users_guide/framework_basics/text_output/#text_encoding","title":"text_encoding","text":"

    ISQ and SI standards always specify symbols using UTF-8 encoding. This is why it is a default and primary target for text output. However, in some applications or environments, a standard portable text output using only the characters from the basic literal character set can be preferred by users.

    This is why the library provides an option to change the default encoding to the portable one with:

    enum class text_encoding : std::int8_t {\n  utf8,       // \u00b5s; m\u00b3;  L\u00b2MT\u207b\u00b3\n  portable,   // us; m^3; L^2MT^-3\n  default_encoding = utf8\n};\n
    "},{"location":"users_guide/framework_basics/text_output/#symbols-of-derived-dimensions","title":"Symbols of derived dimensions","text":""},{"location":"users_guide/framework_basics/text_output/#dimension_symbol_formatting","title":"dimension_symbol_formatting","text":"

    dimension_symbol_formatting is a data type describing the configuration of the symbol generation algorithm.

    struct dimension_symbol_formatting {\n  text_encoding encoding = text_encoding::default_encoding;\n};\n
    "},{"location":"users_guide/framework_basics/text_output/#dimension_symbol","title":"dimension_symbol()","text":"

    Returns a std::string_view with the symbol of a dimension for the provided configuration:

    template<dimension_symbol_formatting fmt = dimension_symbol_formatting{}, typename CharT = char, Dimension D>\n[[nodiscard]] consteval std::string_view dimension_symbol(D);\n

    For example:

    static_assert(dimension_symbol<{.encoding = text_encoding::portable}>(isq::power.dimension) == \"L^2MT^-3\");\n

    Note

    std::string_view is returned only when C++23 is available. Otherwise, an instance of a basic_fixed_string is being returned.

    "},{"location":"users_guide/framework_basics/text_output/#dimension_symbol_to","title":"dimension_symbol_to()","text":"

    Inserts the generated dimension symbol into the output text iterator at runtime.

    template<typename CharT = char, std::output_iterator<CharT> Out, Dimension D>\nconstexpr Out dimension_symbol_to(Out out, D d, dimension_symbol_formatting fmt = dimension_symbol_formatting{});\n

    For example:

    std::string txt;\ndimension_symbol_to(std::back_inserter(txt), isq::power.dimension, {.encoding = text_encoding::portable});\nstd::cout << txt << \"\\n\";\n

    The above prints:

    L^2MT^-3\n
    "},{"location":"users_guide/framework_basics/text_output/#symbols-of-derived-units","title":"Symbols of derived units","text":""},{"location":"users_guide/framework_basics/text_output/#unit_symbol_formatting","title":"unit_symbol_formatting","text":"

    unit_symbol_formatting is a data type describing the configuration of the symbol generation algorithm. It contains three orthogonal fields, each with a default value.

    enum class unit_symbol_solidus : std::int8_t {\n  one_denominator,  // m/s;   kg m\u207b\u00b9 s\u207b\u00b9\n  always,           // m/s;   kg/(m s)\n  never,            // m s\u207b\u00b9; kg m\u207b\u00b9 s\u207b\u00b9\n  default_denominator = one_denominator\n};\n\nenum class unit_symbol_separator : std::int8_t {\n  space,          // kg m\u00b2/s\u00b2\n  half_high_dot,  // kg\u22c5m\u00b2/s\u00b2  (valid only for utf8 encoding)\n  default_separator = space\n};\n\nstruct unit_symbol_formatting {\n  text_encoding encoding = text_encoding::default_encoding;\n  unit_symbol_solidus solidus = unit_symbol_solidus::default_denominator;\n  unit_symbol_separator separator = unit_symbol_separator::default_separator;\n};\n

    unit_symbol_solidus impacts how the division of unit symbols is being presented in the text output. By default, the '/' will be printed if only one unit component is in the denominator. Otherwise, the exponent syntax will be used.

    unit_symbol_separator specifies how multiple multiplied units should be separated from each other. By default, the space (' ') will be used as a separator.

    "},{"location":"users_guide/framework_basics/text_output/#unit_symbol","title":"unit_symbol()","text":"

    Returns a std::string_view with the symbol of a unit for the provided configuration:

    template<unit_symbol_formatting fmt = unit_symbol_formatting{}, typename CharT = char, Unit U>\n[[nodiscard]] consteval std::string_view unit_symbol(U);\n

    For example:

    static_assert(unit_symbol<{.solidus = unit_symbol_solidus::never,\n                           .separator = unit_symbol_separator::half_high_dot}>(kg * m / s2) == \"kg\u22c5m\u22c5s\u207b\u00b2\");\n
    "},{"location":"users_guide/framework_basics/text_output/#unit_symbol_to","title":"unit_symbol_to()","text":"

    Inserts the generated unit symbol into the output text iterator at runtime.

    template<typename CharT = char, std::output_iterator<CharT> Out, Unit U>\nconstexpr Out unit_symbol_to(Out out, U u, unit_symbol_formatting fmt = unit_symbol_formatting{});\n

    For example:

    std::string txt;\nunit_symbol_to(std::back_inserter(txt), kg * m / s2,\n               {.solidus = unit_symbol_solidus::never, .separator = unit_symbol_separator::half_high_dot});\nstd::cout << txt << \"\\n\";\n

    The above prints:

    kg\u22c5m\u22c5s\u207b\u00b2\n
    "},{"location":"users_guide/framework_basics/text_output/#symbols-of-scaled-units","title":"Symbols of scaled units","text":"

    In most cases scaled units are hidden behind named units. However, there are a few real-life where a user directly faces a scaled unit. For example:

    constexpr Unit auto L_per_100km = L / (mag<100> * km);\n

    The above is a derived unit of litre divided by a scaled unit of 100 kilometers. As we can see a scaled unit has a magnitude and a reference unit. To denote the scope of such a unit, we enclose it in [...]. For example, the following:

    std::cout << 6.7 * L_per_100km << \"\\n\";\n

    prints:

    6.7 L/[100 km]\n
    "},{"location":"users_guide/framework_basics/text_output/#symbols-of-common-units","title":"Symbols of common units","text":"

    Some common units expressed with a specialization of the common_unit class template need special printing rules for their symbols. As they represent a minimum set of equivalent common units resulting from the addition or subtraction of multiple quantities, we print all of them as a scaled version of the source unit. For example, the following:

    std::cout << 1 * km + 1 * mi << \"\\n\";\nstd::cout << 1 * nmi + 1 * mi << \"\\n\";\nstd::cout << 1 * km / h + 1 * m / s << \"\\n\";\nstd::cout << 1 * rad + 1 * deg << \"\\n\";\n

    prints:

    40771 [(1/25146 mi), (1/15625 km)]\n108167 [(1/50292 mi), (1/57875 nmi)]\n23 [(1/5 km/h), (1/18 m/s)]\n183.142 [(1/\u03c0\u00b0), (1/180 rad)]\n

    Thanks to the above, it might be easier for the user to reason about the magnitude of the resulting unit and its impact on the value stored in the quantity.

    Note

    It is important to note that this output is provided only for intermediate results of the equations, as shown above. A user usually knows which unit should be used, and explicit conversion can be made to achieve that. For example:

    std::cout << (1 * km + 1 * mi).in<double>(km) << \"\\n\";\n

    prints:

    2.60934 km\n
    "},{"location":"users_guide/framework_basics/text_output/#space_before_unit_symbol-customization-point","title":"space_before_unit_symbol customization point","text":"

    The SI Brochure says:

    SI Brochure

    The numerical value always precedes the unit and a space is always used to separate the unit from the number. ... The only exceptions to this rule are for the unit symbols for degree, minute and second for plane angle, \u00b0, \u2032 and \u2033, respectively, for which no space is left between the numerical value and the unit symbol.

    There are more units with such properties. For example, percent (%) and per mille(\u2030).

    To support the above and other similar cases, the library exposes space_before_unit_symbol customization point. By default, its value is true for all the units, so the space between a number and a unit will be inserted in the output text. To change this behavior, we have to provide a partial specialization for a specific unit:

    template<>\nconstexpr bool space_before_unit_symbol<non_si::degree> = false;\n

    Note

    The above works only for the default formatting or for the format strings that use %? placement field (std::format(\"{}\", q) is equivalent to std::format(\"{:%N%?%U}\", q)).

    In case a user provides custom format specification (e.g., std::format(\"{:%N %U}\", q)), the library will always obey this specification for all the units (no matter what the actual value of the space_before_unit_symbol customization point is) and the separating space will always be used in this case.

    "},{"location":"users_guide/framework_basics/text_output/#output-streams","title":"Output streams","text":"

    Tip

    The output streaming support is opt-in and can be enabled by including the <mp-units/ostream.h> header file.

    The easiest way to print a dimension, unit, or quantity is to provide its object to the output stream:

    const QuantityOf<isq::speed> auto v1 = avg_speed(220. * km, 2 * h);\nconst QuantityOf<isq::speed> auto v2 = avg_speed(140. * mi, 2 * h);\nstd::cout << v1 << '\\n';            // 110 km/h\nstd::cout << v2 << '\\n';            // 70 mi/h\nstd::cout << v2.unit << '\\n';       // mi/h\nstd::cout << v2.dimension << '\\n';  // LT\u207b\u00b9\n

    The text output will always print the value using the default formatting for this entity.

    Important: Don't assume a unit

    Remember that when we deal with a quantity of an \"unknown\" (e.g., auto) type, it is a good practice to always convert the unit to the expected one before passing it to the text output:

    std::cout << v1.in(km / h) << '\\n';       // 110 km/h\nstd::cout << v1.force_in(m / s) << '\\n';  // 30.5556 m/s\n
    "},{"location":"users_guide/framework_basics/text_output/#output-stream-formatting","title":"Output stream formatting","text":"

    Only basic formatting can be applied to output streams. It includes control over width, fill, and alignment.

    The numerical value of the quantity will be printed according to the current stream state and standard manipulators may be used to customize that (assuming that the underlying representation type respects them).

    std::cout << \"|\" << std::setw(10) << 123 * m << \"|\\n\";                       // |     123 m|\nstd::cout << \"|\" << std::setw(10) << std::left << 123 * m << \"|\\n\";          // |123 m     |\nstd::cout << \"|\" << std::setw(10) << std::setfill('*') << 123 * m << \"|\\n\";  // |123 m*****|\n

    Note

    To have more control over the formatting of the quantity that is printed with the output stream just use std::cout << std::format(...).

    "},{"location":"users_guide/framework_basics/text_output/#text-formatting","title":"Text formatting","text":"

    The library provides custom formatters for std::format facility, which allows fine-grained control over what and how it is being printed in the text output.

    Tip

    The text formatting facility support is opt-in and can be enabled by including the <mp-units/format.h> header file.

    "},{"location":"users_guide/framework_basics/text_output/#controlling-width-fill-and-alignment","title":"Controlling width, fill, and alignment","text":"

    Formatting grammar for all the entities provides control over width, fill, and alignment. The C++ standard grammar tokens fill-and-align and width are being used. They treat the entity as a contiguous text to be aligned. For example, here are a few examples of the quantity numerical value and symbol formatting:

    std::println(\"|{:0}|\", 123 * m);     // |123 m|\nstd::println(\"|{:10}|\", 123 * m);    // |     123 m|\nstd::println(\"|{:<10}|\", 123 * m);   // |123 m     |\nstd::println(\"|{:>10}|\", 123 * m);   // |     123 m|\nstd::println(\"|{:^10}|\", 123 * m);   // |  123 m   |\nstd::println(\"|{:*<10}|\", 123 * m);  // |123 m*****|\nstd::println(\"|{:*>10}|\", 123 * m);  // |*****123 m|\nstd::println(\"|{:*^10}|\", 123 * m);  // |**123 m***|\n

    It is important to note that in the second line above, the quantity text is aligned to the right by default, which is consistent with the formatting of numeric types. Units and dimensions behave as text and, thus, are aligned to the left by default.

    Note

    std::println is a C++23 facility. In case we do not have access to C++23, we can obtain the same output with:

    std::cout << std::format(\"<format-string>\\n\", <format-args>);\n
    "},{"location":"users_guide/framework_basics/text_output/#dimension-formatting","title":"Dimension formatting","text":"
    dimension-format-spec = [fill-and-align], [width], [dimension-spec];\ndimension-spec        = [character-set];\ncharacter-set         = 'U' | 'P';\n

    In the above grammar:

    Dimension symbols of some quantities are specified to use Unicode signs by the ISQ (e.g., \u0398 symbol for the thermodynamic temperature dimension). The library follows this by default. From the engineering point of view, sometimes Unicode text might not be the best solution, as terminals of many (especially embedded) devices can output only letters from the basic literal character set. In such a case, the dimension symbol can be forced to be printed using such characters thanks to character-set token:

    std::println(\"{}\", isq::dim_thermodynamic_temperature);   // \u0398\nstd::println(\"{:P}\", isq::dim_thermodynamic_temperature); // O\nstd::println(\"{}\", isq::power.dimension);                 // L\u00b2MT\u207b\u00b3\nstd::println(\"{:P}\", isq::power.dimension);               // L^2MT^-3\n
    "},{"location":"users_guide/framework_basics/text_output/#unit-formatting","title":"Unit formatting","text":"
    unit-format-spec      = [fill-and-align], [width], [unit-spec];\nunit-spec             = [character-set], [unit-symbol-solidus], [unit-symbol-separator], [L]\n                      | [character-set], [unit-symbol-separator], [unit-symbol-solidus], [L]\n                      | [unit-symbol-solidus], [character-set], [unit-symbol-separator], [L]\n                      | [unit-symbol-solidus], [unit-symbol-separator], [character-set], [L]\n                      | [unit-symbol-separator], [character-set], [unit-symbol-solidus], [L]\n                      | [unit-symbol-separator], [unit-symbol-solidus], [character-set], [L];\nunit-symbol-solidus   = '1' | 'a' | 'n';\nunit-symbol-separator = 's' | 'd';\n

    In the above grammar:

    Note

    The above grammar intended that the elements of unit-spec can appear in any order as they have unique characters. Users shouldn't have to remember the order of those tokens to control the formatting of a unit symbol.

    Unit symbols of some quantities are specified to use Unicode signs by the SI (e.g., \u03a9 symbol for the resistance quantity). The library follows this by default. From the engineering point of view, Unicode text might not be the best solution sometimes, as terminals of many (especially embedded) devices can output only letters from the basic literal character set. In such a case, the unit symbol can be forced to be printed using such characters thanks to character-set token:

    std::println(\"{}\", si::ohm);      // \u03a9\nstd::println(\"{:P}\", si::ohm);    // ohm\nstd::println(\"{}\", us);           // \u00b5s\nstd::println(\"{:P}\", us);         // us\nstd::println(\"{}\", m / s2);       // m/s\u00b2\nstd::println(\"{:P}\", m / s2);     // m/s^2\n

    Additionally, both ISO 80000 and SI leave some freedom on how to print unit symbols. This is why two additional tokens were introduced.

    unit-symbol-solidus specifies how the division of units should look like. By default, / will be used only when the denominator contains only one unit. However, with the 'a' or 'n' options, we can force the facility to print the / character always (even when there are more units in the denominator), or never, in which case a parenthesis will be added to enclose all denominator units.

    std::println(\"{}\", m / s);          // m/s\nstd::println(\"{}\", kg / m / s2);    // kg m\u207b\u00b9 s\u207b\u00b2\nstd::println(\"{:a}\", m / s);        // m/s\nstd::println(\"{:a}\", kg / m / s2);  // kg/(m s\u00b2)\nstd::println(\"{:n}\", m / s);        // m s\u207b\u00b9\nstd::println(\"{:n}\", kg / m / s2);  // kg m\u207b\u00b9 s\u207b\u00b2\n

    The unit-symbol-separator token allows us to obtain the following outputs:

    std::println(\"{}\", kg * m2 / s2);    // kg m\u00b2/s\u00b2\nstd::println(\"{:d}\", kg * m2 / s2);  // kg\u22c5m\u00b2/s\u00b2\n

    Note

    'd' requires the UTF-8 encoding to be set.

    "},{"location":"users_guide/framework_basics/text_output/#quantity-formatting","title":"Quantity formatting","text":"
    quantity-format-spec        = [fill-and-align], [width], [quantity-specs], [defaults-specs];\nquantity-specs              = conversion-spec;\n                            | quantity-specs, conversion-spec;\n                            | quantity-specs, literal-char;\nliteral-char                = ? any character other than '{', '}', or '%' ?;\nconversion-spec             = '%', placement-type;\nplacement-type              = subentity-id | '?' | '%';\ndefaults-specs              = ':', default-spec-list;\ndefault-spec-list           = default-spec;\n                            | default-spec-list, default-spec;\ndefault-spec                = subentity-id, '[' format-spec ']';\nsubentity-id                = 'N' | 'U' | 'D';\nformat-spec                 = ? as specified by the formatter for the argument type ?;\n

    In the above grammar:

    "},{"location":"users_guide/framework_basics/text_output/#default-formatting","title":"Default formatting","text":"

    To format quantity values, the formatting facility uses quantity-format-spec. If left empty, the default formatting is applied. The same default formatting is also applied to the output streams. This is why the following code lines produce the same output:

    std::cout << \"Distance: \" << 123 * km << \"\\n\";\nstd::cout << std::format(\"Distance: {}\\n\", 123 * km);\nstd::cout << std::format(\"Distance: {:%N%?%U}\\n\", 123 * km);\n

    Note

    For some quantities, the {:%N %U} format may provide a different output than the default one, as some units have space_before_unit_symbol customization point explicitly set to false (e.g., % and \u00b0).

    "},{"location":"users_guide/framework_basics/text_output/#quantity-numerical-value-unit-symbol-or-both","title":"Quantity numerical value, unit symbol, or both?","text":"

    Thanks to the grammar provided above, the user can easily decide to either:

    "},{"location":"users_guide/framework_basics/text_output/#formatting-of-the-quantity-numerical-value","title":"Formatting of the quantity numerical value","text":"

    The representation type used as a numerical value of a quantity must provide its own formatter specialization. It will be called by the quantity formatter with the format-spec provided by the user in the N defaults specification.

    In case we use C++ fundamental arithmetic types with our quantities the standard formatter specified in format.string.std will be used. The rest of this chapter assumes that it is the case and provides some usage examples.

    sign token allows us to specify how the value's sign is being printed:

    std::println(\"{0},{0::N[+]},{0::N[-]},{0::N[ ]}\", 1 * m);   // 1 m,+1 m,1 m, 1 m\nstd::println(\"{0},{0::N[+]},{0::N[-]},{0::N[ ]}\", -1 * m);  // -1 m,-1 m,-1 m,-1 m\n

    where:

    precision token is allowed only for floating-point representation types:

    std::println(\"{::N[.0]}\", 1.2345 * m);   // 1 m\nstd::println(\"{::N[.1]}\", 1.2345 * m);   // 1 m\nstd::println(\"{::N[.2]}\", 1.2345 * m);   // 1.2 m\nstd::println(\"{::N[.3]}\", 1.2345 * m);   // 1.23 m\nstd::println(\"{::N[.0f]}\", 1.2345 * m);  // 1 m\nstd::println(\"{::N[.1f]}\", 1.2345 * m);  // 1.2 m\nstd::println(\"{::N[.2f]}\", 1.2345 * m);  // 1.23 m\n

    type specifies how a value of the representation type is being printed. For integral types:

    std::println(\"{::N[b]}\", 42 * m);    // 101010 m\nstd::println(\"{::N[B]}\", 42 * m);    // 101010 m\nstd::println(\"{::N[d]}\", 42 * m);    // 42 m\nstd::println(\"{::N[o]}\", 42 * m);    // 52 m\nstd::println(\"{::N[x]}\", 42 * m);    // 2a m\nstd::println(\"{::N[X]}\", 42 * m);    // 2A m\n

    The above can be printed in an alternate version thanks to the # token:

    std::println(\"{::N[#b]}\", 42 * m);   // 0b101010 m\nstd::println(\"{::N[#B]}\", 42 * m);   // 0B101010 m\nstd::println(\"{::N[#o]}\", 42 * m);   // 052 m\nstd::println(\"{::N[#x]}\", 42 * m);   // 0x2a m\nstd::println(\"{::N[#X]}\", 42 * m);   // 0X2A m\n

    For floating-point values, the type token works as follows:

    std::println(\"{::N[a]}\",   1.2345678 * m);      // 1.3c0ca2a5b1d5dp+0 m\nstd::println(\"{::N[.3a]}\", 1.2345678 * m);      // 1.3c1p+0 m\nstd::println(\"{::N[A]}\",   1.2345678 * m);      // 1.3C0CA2A5B1D5DP+0 m\nstd::println(\"{::N[.3A]}\", 1.2345678 * m);      // 1.3C1P+0 m\nstd::println(\"{::N[e]}\",   1.2345678 * m);      // 1.234568e+00 m\nstd::println(\"{::N[.3e]}\", 1.2345678 * m);      // 1.235e+00 m\nstd::println(\"{::N[E]}\",   1.2345678 * m);      // 1.234568E+00 m\nstd::println(\"{::N[.3E]}\", 1.2345678 * m);      // 1.235E+00 m\nstd::println(\"{::N[g]}\",   1.2345678 * m);      // 1.23457 m\nstd::println(\"{::N[g]}\",   1.2345678e8 * m);    // 1.23457e+08 m\nstd::println(\"{::N[.3g]}\", 1.2345678 * m);      // 1.23 m\nstd::println(\"{::N[.3g]}\", 1.2345678e8 * m);    // 1.23e+08 m\nstd::println(\"{::N[G]}\",   1.2345678 * m);      // 1.23457 m\nstd::println(\"{::N[G]}\",   1.2345678e8 * m);    // 1.23457E+08 m\nstd::println(\"{::N[.3G]}\", 1.2345678 * m);      // 1.23 m\nstd::println(\"{::N[.3G]}\", 1.2345678e8 * m);    // 1.23E+08 m\n
    "},{"location":"users_guide/framework_basics/the_affine_space/","title":"The Affine Space","text":"

    The affine space has two types of entities:

    In the following subchapters, we will often refer to displacement vectors simply as vectors for brevity.

    Note

    The displacement vector described here is specific to the affine space theory and is not the same thing as the quantity of a vector character that we discussed in the \"Scalars, vectors, and tensors\" chapter (although, in some cases, those terms may overlap).

    "},{"location":"users_guide/framework_basics/the_affine_space/#operations-in-the-affine-space","title":"Operations in the affine space","text":"

    Here are the primary operations one can do in the affine space:

    Important

    It is not possible to:

    "},{"location":"users_guide/framework_basics/the_affine_space/#points-are-more-common-than-most-of-us-imagine","title":"Points are more common than most of us imagine","text":"

    Point abstractions should be used more often in the C++ software. They are not only about temperature or time. Points are everywhere around us and should become more popular in the products we implement. They can be used to implement:

    Improving the affine space's Points intuition will allow us to write better and safer software.

    "},{"location":"users_guide/framework_basics/the_affine_space/#displacement-vector-is-modeled-by-quantity","title":"Displacement vector is modeled by quantity","text":"

    Up until now, each time we used a quantity in our code, we were modeling some kind of a difference between two things:

    As we already know, a quantity type provides all operations required for a displacement vector abstraction in the affine space. It can be constructed with:

    Note

    The multiply syntax support is disabled for units that provide a point origin in their definition (i.e., units of temperature like K, deg_C, and deg_F).

    "},{"location":"users_guide/framework_basics/the_affine_space/#point-is-modeled-by-quantity_point-and-pointorigin","title":"Point is modeled by quantity_point and PointOrigin","text":"

    In the mp-units library, the Point abstraction is modelled by:

    "},{"location":"users_guide/framework_basics/the_affine_space/#quantity_point","title":"quantity_point","text":"

    The quantity_point class template specifies an absolute quantity measured from a predefined origin:

    template<Reference auto R,\n         PointOriginFor<get_quantity_spec(R)> auto PO = default_point_origin(R),\n         RepresentationOf<get_quantity_spec(R)> Rep = double>\nclass quantity_point;\n

    As we can see above, the quantity_point class template exposes one additional parameter compared to quantity. The PO parameter satisfies a PointOriginFor concept and specifies the origin of our measurement scale.

    Each quantity_point internally stores a quantity object, which represents a displacement vector from the predefined origin. Thanks to this, an instantiation of a quantity_point can be considered as a model of a vector space from such an origin.

    Forcing the user to manually predefine an origin for every domain may be cumbersome and discourage users from using such abstractions at all. This is why, by default, the PO template parameter is initialized with the default_point_origin(R) that provides the quantity points' scale zeroth point using the following rules:

    Quantity points with default point origins may be constructed with the point construction helper or forcing an explicit conversion from the quantity:

    // quantity_point qp1 = 42 * m;           // Compile-time error\n// quantity_point qp2 = 42 * K;           // Compile-time error\n// quantity_point qp3 = delta<deg_C>(42); // Compile-time error\nquantity_point qp4(42 * m);\nquantity_point qp5(42 * K);\nquantity_point qp6(delta<deg_C>(42));\nquantity_point qp7 = point<m>(42);\nquantity_point qp8 = point<K>(42);\nquantity_point qp9 = point<deg_C>(42);\n

    Tip

    The quantity_point definition can be found in the mp-units/quantity_point.h header file.

    "},{"location":"users_guide/framework_basics/the_affine_space/#zeroth_point_originquantityspec","title":"zeroth_point_origin<QuantitySpec>","text":"

    zeroth_point_origin<QuantitySpec> is meant to be used in cases where the specific domain has a well-established, non-controversial, and unique zeroth point on the measurement scale. This saves the user from the need to write a boilerplate code that would predefine such a type for this domain.

    quantity_point<isq::distance[si::metre]> qp1(100 * m);\nquantity_point<isq::distance[si::metre]> qp2 = point<m>(120);\n\nassert(qp1.quantity_from_zero() == 100 * m);\nassert(qp2.quantity_from_zero() == 120 * m);\nassert(qp2.quantity_from(qp1) == 20 * m);\nassert(qp1.quantity_from(qp2) == -20 * m);\n\nassert(qp2 - qp1 == 20 * m);\nassert(qp1 - qp2 == -20 * m);\n\n// auto res = qp1 + qp2;   // Compile-time error\n

    In the above code 100 * m and 120 * m still create two quantities that serve as displacement vectors here. Quantity point objects can be explicitly constructed from such quantities only when their origin is an instantiation of the zeroth_point_origin<QuantitySpec>.

    It is really important to understand that even though we can use .quantity_from_zero() to obtain the displacement vector of a point from the origin, the point by itself does not represent or have any associated physical value. It is just a point in some space. The same point can be expressed with different displacement vectors from different origins.

    It is also worth mentioning that simplicity comes with a safety cost here. For some users, it might be surprising that the usage of zeroth_point_origin<QuantitySpec> makes various quantity point objects compatible as long as quantity types used in the origin and reference are compatible:

    quantity_point<si::metre> qp1{isq::distance(100 * m)};\nquantity_point<si::metre> qp2 = point<isq::height[m]>(120);\n\nassert(qp2.quantity_from(qp1) == 20 * m);\nassert(qp1.quantity_from(qp2) == -20 * m);\nassert(qp2 - qp1 == 20 * m);\nassert(qp1 - qp2 == -20 * m);\n
    "},{"location":"users_guide/framework_basics/the_affine_space/#absolute-point-origin","title":"Absolute point origin","text":"

    In cases where we want to implement an isolated independent space in which points are not compatible with other spaces, even of the same quantity type, we should manually predefine an absolute point origin.

    inline constexpr struct origin final : absolute_point_origin<isq::distance> {} origin;\n\n// quantity_point<si::metre, origin> qp1{100 * m};        // Compile-time error\n// quantity_point<si::metre, origin> qp2{delta<m>(120)};  // Compile-time error\nquantity_point<si::metre, origin> qp1 = origin + 100 * m;\nquantity_point<si::metre, origin> qp2 = 120 * m + origin;\n\n// assert(qp1.quantity_from_zero() == 100 * m);   // Compile-time error\n// assert(qp2.quantity_from_zero() == 120 * m);   // Compile-time error\nassert(qp1.quantity_from(origin) == 100 * m);\nassert(qp2.quantity_from(origin) == 120 * m);\nassert(qp2.quantity_from(qp1) == 20 * m);\nassert(qp1.quantity_from(qp2) == -20 * m);\n\nassert(qp1 - origin == 100 * m);\nassert(qp2 - origin == 120 * m);\nassert(qp2 - qp1 == 20 * m);\nassert(qp1 - qp2 == -20 * m);\n\nassert(origin - qp1 == -100 * m);\nassert(origin - qp2 == -120 * m);\n\n// assert(origin - origin == 0 * m);   // Compile-time error\n

    We can't construct a quantity point directly from the quantity anymore when a custom, named origin is used. To prevent potential safety and maintenance issues, we always need to explicitly provide both a compatible origin and a quantity measured from it to construct a quantity point.

    Said otherwise, a quantity point defined in terms of a specific origin is the result of adding the origin and the displacement vector measured from it to the point we create.

    Info

    A rationale for this longer construction syntax can be found in the Why can't I create a quantity by passing a number to a constructor? chapter.

    Similarly to creation of a quantity, if someone does not like the operator-based syntax to create a quantity_point, the same results can be achieved with a two-parameter constructor:

    quantity_point qp1{100 * m, origin};\n

    Again, CTAD always helps to use precisely the type we need in a current case.

    Additionally, if a quantity point is defined in terms of a custom, named origin, then we can't use a quantity_from_zero() member function anymore. This is to prevent surprises, as our origin may not necessarily be perceived as an absolute zero in the domain we model. Also, as we will learn soon, we can define several related origins in one space, and then it gets harder to understand which one is the \"zero\" one. This is why, to be specific and always correct about the points we use, a quantity_from(QP) member function can be used (where QP can either be an origin or another quantity point).

    Finally, please note that it is not allowed to subtract two point origins defined in terms of absolute_point_origin (e.g., origin - origin) as those do not contain information about the unit, so we cannot determine a resulting quantity type.

    "},{"location":"users_guide/framework_basics/the_affine_space/#modeling-independent-spaces-in-one-domain","title":"Modeling independent spaces in one domain","text":"

    Absolute point origins are also perfect for establishing independent spaces even if the same quantity type and unit is being used:

    inline constexpr struct origin1 final : absolute_point_origin<isq::distance> {} origin1;\ninline constexpr struct origin2 final : absolute_point_origin<isq::distance> {} origin2;\n\nquantity_point qp1 = origin1 + 100 * m;\nquantity_point qp2 = origin2 + 120 * m;\n\nassert(qp1.quantity_from(origin1) == 100 * m);\nassert(qp2.quantity_from(origin2) == 120 * m);\n\nassert(qp1 - origin1 == 100 * m);\nassert(qp2 - origin2 == 120 * m);\nassert(origin1 - qp1 == -100 * m);\nassert(origin2 - qp2 == -120 * m);\n\n// assert(qp2 - qp1 == 20 * m);                    // Compile-time error\n// assert(qp1 - origin2 == 100 * m);               // Compile-time error\n// assert(qp2 - origin1 == 120 * m);               // Compile-time error\n// assert(qp2.quantity_from(qp1) == 20 * m);       // Compile-time error\n// assert(qp1.quantity_from(origin2) == 100 * m);  // Compile-time error\n// assert(qp2.quantity_from(origin1) == 120 * m);  // Compile-time error\n
    "},{"location":"users_guide/framework_basics/the_affine_space/#relative-point-origin","title":"Relative Point origin","text":"

    We often do not have only one ultimate \"zero\" point when we measure things. Often, we have one common scale, but we measure various quantities relative to different points and expect those points to be compatible. There are many examples here, but probably the most common are temperatures, timestamps, and altitudes.

    For such cases, relative point origins should be used:

    inline constexpr struct A final : absolute_point_origin<isq::distance> {} A;\ninline constexpr struct B final : relative_point_origin<A + 10 * m> {} B;\ninline constexpr struct C final : relative_point_origin<B + 10 * m> {} C;\ninline constexpr struct D final : relative_point_origin<A + 30 * m> {} D;\n\nquantity_point qp1 = C + 100 * m;\nquantity_point qp2 = D + 120 * m;\n\nassert(qp1.quantity_ref_from(qp1.point_origin) == 100 * m);\nassert(qp2.quantity_ref_from(qp2.point_origin) == 120 * m);\n\nassert(qp2.quantity_from(qp1) == 30 * m);\nassert(qp1.quantity_from(qp2) == -30 * m);\nassert(qp2 - qp1 == 30 * m);\nassert(qp1 - qp2 == -30 * m);\n\nassert(qp1.quantity_from(A) == 120 * m);\nassert(qp1.quantity_from(B) == 110 * m);\nassert(qp1.quantity_from(C) == 100 * m);\nassert(qp1.quantity_from(D) == 90 * m);\nassert(qp1 - A == 120 * m);\nassert(qp1 - B == 110 * m);\nassert(qp1 - C == 100 * m);\nassert(qp1 - D == 90 * m);\n\nassert(qp2.quantity_from(A) == 150 * m);\nassert(qp2.quantity_from(B) == 140 * m);\nassert(qp2.quantity_from(C) == 130 * m);\nassert(qp2.quantity_from(D) == 120 * m);\nassert(qp2 - A == 150 * m);\nassert(qp2 - B == 140 * m);\nassert(qp2 - C == 130 * m);\nassert(qp2 - D == 120 * m);\n\nassert(B - A == 10 * m);\nassert(C - A == 20 * m);\nassert(D - A == 30 * m);\nassert(D - C == 10 * m);\n\nassert(B - B == 0 * m);\n// assert(A - A == 0 * m);  // Compile-time error\n

    Note

    Even though we can't subtract two absolute point origins from each other, it is possible to subtract relative ones or relative and absolute ones.

    "},{"location":"users_guide/framework_basics/the_affine_space/#converting-between-different-representations-of-the-same-point","title":"Converting between different representations of the same point","text":"

    As we might represent the same point with displacement vectors from various origins, the library provides facilities to convert the same point to the quantity_point class templates expressed in terms of different origins.

    For this purpose, we can use either:

    It is important to understand that all such translations still describe exactly the same point (e.g., all of them compare equal):

    assert(qp2 == qp2C);\nassert(qp2 == qp2B);\nassert(qp2 == qp2A);\n

    Important

    It is only allowed to convert between various origins defined in terms of the same absolute_point_origin. Even if it is possible to express the same point as a displacement vector from another absolute_point_origin, the library will not provide such a conversion. A custom user-defined conversion function will be needed to add such a functionality.

    Said another way, in the library, there is no way to spell how two distinct absolute_point_origin types relate to each other.

    "},{"location":"users_guide/framework_basics/the_affine_space/#temperature-support","title":"Temperature support","text":"

    Support for temperature quantity points is probably one of the most common examples of relative point origins in action that we use in daily life.

    The SI definition in the library provides a few predefined point origins for this purpose:

    namespace si {\n\ninline constexpr struct absolute_zero final : absolute_point_origin<isq::thermodynamic_temperature> {} absolute_zero;\ninline constexpr auto zeroth_kelvin = absolute_zero;\n\ninline constexpr struct ice_point final : relative_point_origin<point<milli<kelvin>>(273'150)}> {} ice_point;\ninline constexpr auto zeroth_degree_Celsius = ice_point;\n\n}\n\nnamespace usc {\n\ninline constexpr struct zeroth_degree_Fahrenheit final :\n  relative_point_origin<point<mag_ratio<5, 9> * si::degree_Celsius>(-32)> {} zeroth_degree_Fahrenheit;\n\n}\n

    The above is a great example of how point origins can be stacked on top of each other:

    Note

    Notice that while stacking point origins, we can use different representation types and units for origins and a point. In the above example, the relative point origin for degree Celsius is defined in terms of si::kelvin, while the quantity point for it will use si::degree_Celsius as a unit.

    The temperature point origins defined above are provided explicitly in the respective units' definitions:

    namespace si {\n\ninline constexpr struct kelvin final :\n    named_unit<\"K\", kind_of<isq::thermodynamic_temperature>, zeroth_kelvin> {} kelvin;\ninline constexpr struct degree_Celsius final :\n    named_unit<{u8\"\u2103\", \"`C\"}, kelvin, zeroth_degree_Celsius> {} degree_Celsius;\n\n}\n\nnamespace usc {\n\ninline constexpr struct degree_Fahrenheit final :\n    named_unit<{u8\"\u2109\", \"`F\"}, mag_ratio<5, 9> * si::degree_Celsius,\n               zeroth_degree_Fahrenheit> {} degree_Fahrenheit;\n\n}\n

    As it was described above, default_point_origin(R) returns a zeroth_point_origin<QuantitySpec> when a unit does not provide any origin in its definition. As of today, the units of temperature are the only ones in the entire mp-units library that provide such origins.

    Now, let's see how we can benefit from the above definitions. We have quite a few alternatives to choose from here. Depending on our needs or tastes, we can:

    In all of the above cases, we end up with the quantity_point of the same type and value.

    To play a bit more with temperatures, we can implement a simple room AC temperature controller in the following way:

    constexpr struct room_reference_temp final : relative_point_origin<point<deg_C>(21)> {} room_reference_temp;\nusing room_temp = quantity_point<isq::Celsius_temperature[deg_C], room_reference_temp>;\n\nconstexpr auto step_delta = delta<isq::Celsius_temperature<deg_C>>(0.5);\nconstexpr int number_of_steps = 6;\n\nroom_temp room_ref{};\nroom_temp room_low = room_ref - number_of_steps * step_delta;\nroom_temp room_high = room_ref + number_of_steps * step_delta;\n\nstd::println(\"Room reference temperature: {} ({}, {::N[.2f]})\\n\",\n             room_ref.quantity_from_zero(),\n             room_ref.in(usc::degree_Fahrenheit).quantity_from_zero(),\n             room_ref.in(si::kelvin).quantity_from_zero());\n\nstd::println(\"| {:<18} | {:^18} | {:^18} | {:^18} |\",\n             \"Temperature delta\", \"Room reference\", \"Ice point\", \"Absolute zero\");\nstd::println(\"|{0:=^20}|{0:=^20}|{0:=^20}|{0:=^20}|\", \"\");\n\nauto print_temp = [&](std::string_view label, auto v) {\n  std::println(\"| {:<14} | {:^18} | {:^18} | {:^18:N[.2f]} |\", label,\n               v - room_reference_temp, (v - si::ice_point).in(deg_C), (v - si::absolute_zero).in(deg_C));\n};\n\nprint_temp(\"Lowest\", room_low);\nprint_temp(\"Default\", room_ref);\nprint_temp(\"Highest\", room_high);\n

    The above prints:

    Room reference temperature: 21 \u2103 (69.8 \u2109, 294.15 K)\n\n| Temperature delta  |   Room reference   |     Ice point      |   Absolute zero    |\n|====================|====================|====================|====================|\n| Lowest             |       -3 \u2103        |       18 \u2103        |     291.15 \u2103      |\n| Default            |        0 \u2103        |       21 \u2103        |     294.15 \u2103      |\n| Highest            |        3 \u2103        |       24 \u2103        |     297.15 \u2103      |\n
    "},{"location":"users_guide/framework_basics/the_affine_space/#no-text-output-for-points","title":"No text output for Points","text":"

    The library does not provide a text output for quantity points. The quantity stored inside is just an implementation detail of this type. It is a vector from a specific origin. Without the knowledge of the origin, the vector by itself is useless as we can't determine which point it describes.

    In the current library design, point origin does not provide any text in its definition. Even if we could add such information to the point's definition, we would not know how to output it in the text. There may be many ways to do it. For example, should we prepend or append the origin part to the quantity text?

    For example, the text output of 42 m for a quantity point may mean many things. It may be an offset from the mountain top, sea level, or maybe the center of Mars. Printing 42 m AMSL for altitudes above mean sea level is a much better solution, but the library does not have enough information to print it that way by itself.

    "},{"location":"users_guide/framework_basics/the_affine_space/#the-affine-space-is-about-type-safety","title":"The affine space is about type-safety","text":"

    The following operations are not allowed in the affine space:

    Important: The affine space improves safety

    The usage of quantity_point and affine space types, in general, improves expressiveness and type-safety of the code we write.

    "},{"location":"users_guide/framework_basics/value_conversions/","title":"Value Conversions","text":"

    One of the most important features of every unit library is to provide support for compile-time-enabled conversions of a numerical value of a quantity.

    A numerical value of a quantity depends on two elements:

    Changing any of the above may require changing the value stored in a quantity.

    "},{"location":"users_guide/framework_basics/value_conversions/#value-preserving-conversions","title":"Value-preserving conversions","text":"
    auto q1 = 5 * km;\nstd::cout << q1.in(m) << '\\n';\nquantity<si::metre, int> q2 = q1;\n

    The second line above converts the current quantity to the one expressed in meters and prints its contents. The third line converts the quantity expressed in kilometers into the one measured in meters.

    In case a user would like to perform an opposite transformation:

    auto q1 = 5 * m;\nstd::cout << q1.in(km) << '\\n';\nquantity<si::kilo<si::metre>, int> q2 = q1;\n

    Both conversions will fail to compile.

    There are two ways to make the above work. The first solution is to use a floating-point representation type:

    auto q1 = 5. * m;\nstd::cout << q1.in(km) << '\\n';\nquantity<si::kilo<si::metre>> q2 = q1;\n

    or

    auto q1 = 5 * m;\nstd::cout << value_cast<double>(q1).in(km) << '\\n';\nquantity<si::kilo<si::metre>> q2 = q1;  // double by default\n

    Important

    The mp-units library follows std::chrono::duration logic and treats floating-point types as value-preserving.

    "},{"location":"users_guide/framework_basics/value_conversions/#value-truncating-conversions","title":"Value-truncating conversions","text":"

    The second solution is to force a truncating conversion:

    auto q1 = 5 * m;\nstd::cout << value_cast<km>(q1) << '\\n';\nquantity<si::kilo<si::metre>, int> q2 = q1.force_in(km);\n

    This explicit cast makes it clear that something unsafe is going on. It is easy to spot in code reviews or while chasing a bug in the source code.

    Note

    q.force_in(U) is just a shortcut to run value_cast<U>(q). There is no difference in behavior between those two interfaces. q.force_in(U) was added for consistency with q.in(U) and q.force_numerical_value_in(U).

    Another place where this cast is useful is when a user wants to convert a quantity with a floating-point representation to the one using an integral one. Again, this is a truncating conversion, so an explicit cast is needed:

    quantity<si::metre, int> q3 = value_cast<int>(3.14 * m);\n

    Info

    It is often OK to use an integral as a representation type, but in general, floating-point types provide better precision and are privileged in the library as they are considered to be value-preserving.

    In some cases, a unit and a representation type should be changed simultaneously. Moreover, sometimes, the order of doing those operations matters. In such cases, the library provides the value_cast<U, Rep>(q) which always returns the most precise result:

    C++23C++20Portable 
    inline constexpr struct dim_currency final : base_dimension<\"$\"> {} dim_currency;\ninline constexpr struct currency final : quantity_spec<dim_currency> {} currency;\n\ninline constexpr struct us_dollar final : named_unit<\"USD\", kind_of<currency>> {} us_dollar;\ninline constexpr struct scaled_us_dollar final : named_unit<\"USD_s\", mag_power<10, -8> * us_dollar> {} scaled_us_dollar;\n\nnamespace unit_symbols {\n\ninline constexpr auto USD = us_dollar;\ninline constexpr auto USD_s = scaled_us_dollar;\n\n}  // namespace unit_symbols\n\nusing Price = quantity_point<currency[us_dollar]>;\nusing Scaled = quantity_point<currency[scaled_us_dollar], zeroth_point_origin<currency>, std::int64_t>;\n
    inline constexpr struct dim_currency final : base_dimension<\"$\"> {} dim_currency;\ninline constexpr struct currency final : quantity_spec<currency, dim_currency> {} currency;\n\ninline constexpr struct us_dollar final : named_unit<\"USD\", kind_of<currency>> {} us_dollar;\ninline constexpr struct scaled_us_dollar final : named_unit<\"USD_s\", mag_power<10, -8> * us_dollar> {} scaled_us_dollar;\n\nnamespace unit_symbols {\n\ninline constexpr auto USD = us_dollar;\ninline constexpr auto USD_s = scaled_us_dollar;\n\n}  // namespace unit_symbols\n\nusing Price = quantity_point<currency[us_dollar]>;\nusing Scaled = quantity_point<currency[scaled_us_dollar], zeroth_point_origin<currency>, std::int64_t>;\n
    inline constexpr struct dim_currency final : base_dimension<\"$\"> {} dim_currency;\nQUANTITY_SPEC(currency, dim_currency);\n\ninline constexpr struct us_dollar final : named_unit<\"USD\", kind_of<currency>> {} us_dollar;\ninline constexpr struct scaled_us_dollar final : named_unit<\"USD_s\", mag_power<10, -8> * us_dollar> {} scaled_us_dollar;\n\nnamespace unit_symbols {\n\ninline constexpr auto USD = us_dollar;\ninline constexpr auto USD_s = scaled_us_dollar;\n\n}  // namespace unit_symbols\n\nusing Price = quantity_point<currency[us_dollar]>;\nusing Scaled = quantity_point<currency[scaled_us_dollar], zeroth_point_origin<currency>, std::int64_t>;\n
    using namespace unit_symbols;\nPrice price{12.95 * USD};\nScaled spx = value_cast<USD_s, std::int64_t>(price);\n

    As a shortcut, instead of providing a unit and a representation type to value_cast, you may also provide a Quantity type directly, from which unit and representation type are taken. However, value_cast<Quantity>, still only allows for changes in unit and representation type, but not changing the type of the quantity. For that, you will have to use a quantity_cast instead.

    Overloads are also provided for instances of quantity_point. All variants of value_cast<...>(q) that apply to instances of quantity have a corresponding version applicable to quantity_point, where the point_origin remains untouched, and the cast changes how the \"offset\" from the origin is represented. Specifically, for any quantity_point instance qp, all of the following equivalences hold:

    static_assert(value_cast<Rep>(qp) == quantity_point{value_cast<Rep>(qp.quantity_from(qp.point_origin)), qp.point_origin});\nstatic_assert(value_cast<U>(qp) == quantity_point{value_cast<U>(qp.quantity_from(qp.point_origin)), qp.point_origin});\nstatic_assert(value_cast<U, Rep>(qp) == quantity_point{value_cast<U, Rep>(qp.quantity_from(qp.point_origin)), qp.point_origin});\nstatic_assert(value_cast<Q>(qp) == quantity_point{value_cast<Q>(qp.quantity_from(qp.point_origin)), qp.point_origin});\n

    Furthermore, there is one additional overload value_cast<ToQP>(qp). This overload permits to additionally replace the point_origin with another compatible one, while still representing the same point in the affine space. Thus, it is roughly equivalent to value_cast<ToQP::unit, ToQP::rep>(qp).point_for(ToQP::point_origin). In contrast to a separate value_cast followed by point_for (or vice-versa), the combined value_cast tries to choose the order of the individual conversion steps in a way to avoid both overflow and unnecessary loss of precision. Overflow is a risk because the change of origin point may require an addition of a potentially large offset (the difference between the origin points), which may well be outside the range of one or both quantity types.

    "},{"location":"users_guide/framework_basics/value_conversions/#scaling-overflow-prevention","title":"Scaling overflow prevention","text":"

    In the case of small integral types, it is easy to overflow the representation type for every value besides 0 while performing simple and popular unit conversions. This is why the library prevents such invalid conversions at compile-time both for explicit and implicit conversions:

    quantity q1 = std::int8_t(1) * km;\nquantity q2 = q1.force_in(m);   // Compile-time error (1)\nif(q1 != 1 * m) { /* ... */ }   // Compile-time error (2)\n
    1. Forced conversion would overflow on scaling.
    2. Implicit conversion that brings arguments to a common unit before comparison would overflow on scaling.

    In the above example, the conversion factor between km and m is 1'000, which is larger than the maximum value that can be stored in std::int8_t. Even if we want to convert the smallest possible integral amount (e.g., 1 km), we will overflow the quantity representation type. We decided not to allow such conversions for safety reasons despite the value of 0 km would work.

    "},{"location":"users_guide/framework_basics/value_conversions/#value-conversions-summary","title":"Value conversions summary","text":"

    The table below provides all the value conversion functions that may be run on x being the instance of either quantity or quantity_point:

    Forcing Representation Unit Member function Non-member function No Same u x.in(u) No T Same x.in<T>() No T u x.in<T>(u) Yes Same u x.force_in(u) value_cast<u>(x) Yes T Same x.force_in<T>() value_cast<T>(x) Yes T u x.force_in<T>(u) value_cast<u, T>(x) or value_cast<T, u>(x)"},{"location":"users_guide/systems/strong_angular_system/","title":"Strong Angular System","text":""},{"location":"users_guide/systems/strong_angular_system/#some-background-information","title":"Some background information","text":"

    As per today's SI, both radian and steradian are dimensionless. This forces the convention to set the angle 1 radian equal to the number 1 within equations (similar to what natural units system does for c constant).

    Following Wikipedia:

    Wikipedia: Radian - Dimensional analysis

    Giacomo Prando says \"the current state of affairs leads inevitably to ghostly appearances and disappearances of the radian in the dimensional analysis of physical equations.\" For example, a mass hanging by a string from a pulley will rise or drop by \\(y=r\u03b8\\) centimeters, where \\(r\\) is the radius of the pulley in centimeters and \\(\u03b8\\) is the angle the pulley turns in radians. When multiplying \\(r\\) by \\(\u03b8\\) the unit of radians disappears from the result. Similarly in the formula for the angular velocity of a rolling wheel, \\(\u03c9=v/r\\), radians appear in the units of \\(\u03c9\\) but not on the right hand side. Anthony French calls this phenomenon \"a perennial problem in the teaching of mechanics\". Oberhofer says that the typical advice of ignoring radians during dimensional analysis and adding or removing radians in units according to convention and contextual knowledge is \"pedagogically unsatisfying\".

    At least a dozen scientists have made proposals to treat the radian as a base unit of measure defining its own dimension of \"angle\", as early as 1936 and as recently as 2022. This would bring the advantages of a physics-based, consistent, and logically-robust unit system, with unambiguous units for all physical quantities. At the same time the only notable changes for typical end-users would be: improved units for the quantities torque, angular momentum, and moment of inertia.

    Paul Quincey in his proposal \"Angles in the SI: a detailed proposal for solving the problem\" states:

    Paul Quincey: Angles in the SI: a detailed proposal for solving the problem

    The familiar units assigned to some angular quantities are based on equations that have adopted the radian convention, and so are missing rads that would be present if the complete equation is used. The physically-correct units are those with the rads reinstated. Numerical values would not change, and the physical meanings of all quantities would also be unaffected.

    He proposes the following changes:

    Paul Quincey summarizes that with the above in action:

    Paul Quincey: Angles in the SI: a detailed proposal for solving the problem

    However, the physical clarity this would build into the SI should be recognised very quickly. The units would tell us that \\(torque \\times angle = energy\\), and \\(angular\\:momentum \\times angle = action\\), for example, in the same way that they do for \\(force \\times distance = energy\\), \\(linear\\:momentum \\times distance = action\\), and \\(radiant\\:intensity \\times solid\\:angle = radiant\\:flux\\). Dimensional analysis could be used to its full extent. Software involving angular quantities would be rationalised. Arguments about the correct units for frequency and angular frequency, and the meaning of the unit \\(Hz\\), could be left behind. The explanation of these changes would be considerably easier and more rewarding than explaining how a kilogram-sized mass can be measured in terms of the Planck constant.

    "},{"location":"users_guide/systems/strong_angular_system/#angular-quantities-in-the-si","title":"Angular quantities in the SI","text":"

    Even though the SI somehow ignores the dimensionality of angle:

    SI Brochure

    Plane and solid angles, when expressed in radians and steradians respectively, are in effect also treated within the SI as quantities with the unit one. The symbols \\(rad\\) and \\(sr\\) are written explicitly where appropriate, in order to emphasize that, for radians or steradians, the quantity being considered is, or involves the plane angle or solid angle respectively. For steradians it emphasizes the distinction between units of flux and intensity in radiometry and photometry for example. However, it is a long-established practice in mathematics and across all areas of science to make use of \\(rad = 1\\) and \\(sr = 1\\). For historical reasons the radian and steradian are treated as derived units.

    It also explicitly states:

    SI Brochure

    The SI unit of frequency is hertz, the SI unit of angular velocity and angular frequency is radian per second, and the SI unit of activity is becquerel, implying counts per second. Although it is formally correct to write all three of these units as the reciprocal second, the use of the different names emphasizes the different nature of the quantities concerned. It is especially important to carefully distinguish frequencies from angular frequencies, because by definition their numerical values differ by a factor of \\(2\\pi\\). Ignoring this fact may cause an error of \\(2\\pi\\). Note that in some countries, frequency values are conventionally expressed using \u201ccycle/s\u201d or \u201ccps\u201d instead of the SI unit \\(Hz\\), although \u201ccycle\u201d and \u201ccps\u201d are not units in the SI. Note also that it is common, although not recommended, to use the term frequency for quantities expressed in \\(rad/s\\). Because of this, it is recommended that quantities called \u201cfrequency\u201d, \u201cangular frequency\u201d, and \u201cangular velocity\u201d always be given explicit units of \\(Hz\\) or \\(rad/s\\) and not \\(s^{-1}\\).

    "},{"location":"users_guide/systems/strong_angular_system/#strong-angular-extensions-in-the-library","title":"Strong Angular extensions in the library","text":"

    The mp-units library strives to define physically-correct quantities and their units to provide maximum help to its users. As treating angle as a dimensional quantity can lead to many \"trivial\" mistakes in dimensional analysis and calculation, it was decided to provide additional experimental systems of quantities and units that follow the above approach and treat angle as a base quantity with a base unit of radian and solid angle as its derived quantity.

    As those (at least for now) are not a part of SI, the plain angle and solid angle definitions can be found in a dedicated angular system. Those definitions are also used in the isq_angle system of quantities to make the recipes for angle-based quantities like torque or angular velocity physically correct:

    using namespace mp_units;\nusing namespace mp_units::si::unit_symbols;\nusing mp_units::angular::unit_symbols::deg;\nusing mp_units::angular::unit_symbols::rad;\n\nconst quantity lever = isq_angle::position_vector(20 * cm);\nconst quantity force = isq_angle::force(500 * N);\nconst quantity angle = isq_angle::angular_measure(90. * deg);\nconst quantity torque = isq_angle::torque(lever * force * angular::sin(angle) / (1 * isq_angle::cotes_angle));\n\nstd::cout << \"Applying a perpendicular force of \" << force << \" to a \" << lever << \" long lever results in \"\n          << torque.in(N * m / rad) << \" of torque.\\n\";\n

    The above program prints:

    Applying a perpendicular force of 500 N to a 20 cm long lever results in 100 N m/rad of torque.\n

    Note

    cotes_angle is a constant which represents an angle with the value of exactly 1 radian. You can find more information about this constant in Quincey.

    Try it on Compiler Explorer

    "},{"location":"users_guide/use_cases/interoperability_with_other_libraries/","title":"Interoperability with Other Libraries","text":"

    mp-units makes it easy to cooperate with similar entities of other libraries. No matter if we want to provide interoperability with a simple home-grown strongly typed wrapper type (e.g., Meter, Timestamp, ...) or with a feature-rich quantities and units library, we have to provide specializations of:

    "},{"location":"users_guide/use_cases/interoperability_with_other_libraries/#specifying-a-conversion-kind","title":"Specifying a conversion kind","text":"

    Before we delve into the template specialization details, let's first decide if we want the conversions to happen implicitly or if explicit ones would be a better choice. Or maybe the conversion should be implicit in one direction only (e.g., into mp-units abstractions) while the explicit conversions in the other direction should be preferred?

    There is no one unified answer to the above questions. Everything depends on the use case.

    Typically, the implicit conversions are allowed in cases where:

    In all other scenarios, we should probably enforce explicit conversions.

    The kinds of inter-library conversions can be easily configured in partial specializations of conversion traits in the mp-units library. Conversion traits should provide a static data member convertible to bool. If the value is true, then the conversion is explicit. Otherwise, if the value is false, implicit conversions will be allowed. The names of the flags are as follows:

    "},{"location":"users_guide/use_cases/interoperability_with_other_libraries/#quantities-conversions","title":"Quantities conversions","text":"

    For example, let's assume that some company has its own Meter strong-type wrapper:

    struct Meter {\n  int value;\n};\n

    As every usage of Meter is at least as good and safe as the usage of quantity<si::metre, int>, and as there is no significant runtime performance penalty, we would like to allow the conversion to mp_units::quantity to happen implicitly.

    On the other hand, the quantity type is much safer than the Meter, and that is why we would prefer to see the opposite conversions stated explicitly in our code.

    To enable such interoperability, we must define a partial specialization of the quantity_like_traits<T> type trait. Such specialization should provide:

    For example, for our Meter type, we could provide the following:

    template<>\nstruct mp_units::quantity_like_traits<Meter> {\n  static constexpr auto reference = si::metre;\n  static constexpr bool explicit_import = false;\n  static constexpr bool explicit_export = true;\n  using rep = decltype(Meter::value);\n  static constexpr rep to_numerical_value(Meter m) { return m.value; }\n  static constexpr Meter from_numerical_value(rep v) { return Meter{v}; }\n};\n

    After that, we can check that the QuantityLike concept is satisfied:

    static_assert(mp_units::QuantityLike<Meter>);\n

    and we can write the following:

    void print(Meter m) { std::cout << m.value << \" m\\n\"; }\n\nint main()\n{\n  using namespace mp_units;\n  using namespace mp_units::si::unit_symbols;\n\n  Meter height{42};\n\n  // implicit conversions\n  quantity h1 = height;\n  quantity<isq::height[m], int> h2 = height;\n\n  std::cout << h1 << \"\\n\";\n  std::cout << h2 << \"\\n\";\n\n  // explicit conversions\n  print(Meter(h1));\n  print(Meter(h2));\n}\n

    Note

    No matter if we decide to use implicit or explicit conversions, the mp-units will not allow unsafe operations to happen.

    If we extend the above example with unsafe conversions, the code will not compile, and we will have to fix the issues first before the conversion may be performed:

    UnsafeFixed 
    quantity<isq::height[m]> h3 = height;\nquantity<isq::height[mm], int> h4 = height;\nquantity<isq::height[km], int> h5 = height;  // Compile-time error (1)\n\nstd::cout << h3 << \"\\n\";\nstd::cout << h4 << \"\\n\";\nstd::cout << h5 << \"\\n\";\n\nprint(Meter(h3));                            // Compile-time error (2)\nprint(Meter(h4));                            // Compile-time error (3)\nprint(Meter(h5));\n
    1. Truncation of value while converting from meters to kilometers.
    2. Conversion of double to int is not value-preserving.
    3. Truncation of value while converting from millimeters to meters.
    quantity<isq::height[m]> h3 = height;\nquantity<isq::height[mm], int> h4 = height;\nquantity<isq::height[km], int> h5 = quantity{height}.force_in(km);\n\nstd::cout << h3 << \"\\n\";\nstd::cout << h4 << \"\\n\";\nstd::cout << h5 << \"\\n\";\n\nprint(Meter(value_cast<int>(h3)));\nprint(Meter(h4.force_in(m)));\nprint(Meter(h5));\n
    "},{"location":"users_guide/use_cases/interoperability_with_other_libraries/#quantity-points-conversions","title":"Quantity points conversions","text":"

    To play with quantity point conversions, let's assume that we have a Timestamp strong type in our codebase, and we would like to start using mp-units to work with this abstraction.

    struct Timestamp {\n  int seconds;\n};\n

    As we described in The Affine Space chapter, timestamps should be modeled as quantity points rather than regular quantities.

    To allow the conversion between our custom Timestamp type and the quantity_point class template we need to provide the following in the partial specialization of the quantity_point_like_traits<T> type trait:

    For example, for our Timestamp type, we could provide the following:

    template<>\nstruct mp_units::quantity_point_like_traits<Timestamp> {\n  static constexpr auto reference = si::second;\n  static constexpr auto point_origin = default_point_origin(reference);\n  static constexpr bool explicit_import = false;\n  static constexpr bool explicit_export = true;\n  using rep = decltype(Timestamp::seconds);\n  static constexpr rep to_numerical_value(Timestamp ts) { return ts.seconds; }\n  static constexpr Timestamp from_numerical_value(rep v) { return Timestamp(v); }\n};\n

    After that, we can check that the QuantityPointLike concept is satisfied:

    static_assert(mp_units::QuantityPointLike<Timestamp>);\n

    and we can write the following:

    void print(Timestamp ts) { std::cout << ts.seconds << \" s\\n\"; }\n\nint main()\n{\n  using namespace mp_units;\n  using namespace mp_units::si::unit_symbols;\n\n  Timestamp ts{42};\n\n  // implicit conversion\n  quantity_point qp = ts;\n\n  std::cout << qp.quantity_from_zero() << \"\\n\";\n\n  // explicit conversion\n  print(Timestamp(qp));\n}\n
    "},{"location":"users_guide/use_cases/interoperability_with_other_libraries/#interoperability-with-the-c-standard-library","title":"Interoperability with the C++ Standard Library","text":"

    In the C++ standard library, we have two types that handle quantities and model the affine space. Those are:

    The mp-units library comes with built-in interoperability with those types. It is enough to include the mp-units/systems/si/chrono.h file to benefit from it. This file provides:

    Important

    Only a quantity_point that uses chrono_point_origin<Clock> as its origin can be converted to the std::chrono abstractions:

    inline constexpr struct ts_origin final : relative_point_origin<chrono_point_origin<system_clock> + 1 * h> {} ts_origin;\ninline constexpr struct my_origin final : absolute_point_origin<isq::time> {} my_origin;\n\nquantity_point qp1 = sys_seconds{1s};\nauto tp1 = to_chrono_time_point(qp1);  // OK\n\nquantity_point qp2 = chrono_point_origin<system_clock> + 1 * s;\nauto tp2 = to_chrono_time_point(qp2);  // OK\n\nquantity_point qp3 = ts_origin + 1 * s;\nauto tp3 = to_chrono_time_point(qp3);  // OK\n\nquantity_point qp4 = my_origin + 1 * s;\nauto tp4 = to_chrono_time_point(qp4);  // Compile-time Error (1)\n\nquantity_point qp5{1 * s};\nauto tp5 = to_chrono_time_point(qp5);  // Compile-time Error (2)\n
    1. my_origin is not defined in terms of chrono_point_origin<Clock>.
    2. zeroth_point_origin is not defined in terms of chrono_point_origin<Clock>.

    Here is an example of how interoperability described in this chapter can be used in practice:

    using namespace std::chrono;\n\nsys_seconds ts_now = floor<seconds>(system_clock::now());\n\nquantity_point start_time = ts_now;\nquantity speed = 925. * km / h;\nquantity distance = 8111. * km;\nquantity flight_time = distance / speed;\nquantity_point exp_end_time = start_time + flight_time;\n\nsys_seconds ts_end = value_cast<int>(exp_end_time.in(s));\n\nauto curr_time = zoned_time(current_zone(), ts_now);\nauto mst_time = zoned_time(\"America/Denver\", ts_end);\n\nstd::cout << \"Takeoff: \" << curr_time << \"\\n\";\nstd::cout << \"Landing: \" << mst_time << \"\\n\";\n

    The above may print the following output:

    Takeoff: 2023-11-18 13:20:54 UTC\nLanding: 2023-11-18 15:07:01 MST\n
    "},{"location":"users_guide/use_cases/wide_compatibility/","title":"Wide Compatibility","text":"

    The mp-units allows us to implement nice and terse code targeting a specific C++ version and configuration. Such code is easy to write and understand but might not be portable to some older environments.

    However, sometimes, we want to develop code that can be compiled on a wide range of various compilers and configurations. This is why the library also exposes and uses special preprocessor macros that can be used to ensure the wide compatibility of our code.

    Note

    Those macros are used in our short example applications as those are meant to be built on all of the supported compilers. Some still do not support std::format, C++ modules, or C++ versions newer than C++20.

    "},{"location":"users_guide/use_cases/wide_compatibility/#various-compatibility-options","title":"Various compatibility options","text":"

    Depending on your compiler's conformance, you can choose to use any of the below styles to write your code using mp-units:

    C++23C++20C++20 with header filesC++20 with header files + libfmtWide Compatibility 
    #include <format>\n#include <iostream>\nimport mp_units;\n\n// ...\n\ninline constexpr struct horizontal_length final : quantity_spec<isq::length> {} horizontal_length;\n\n// ...\n\nstd::cout << std::format(...) << \"\\n\";\n
    #include <format>\n#include <iostream>\nimport mp_units;\n\n// ...\n\ninline constexpr struct horizontal_length final : quantity_spec<horizontal_length, isq::length> {} horizontal_length;\n\n// ...\n\nstd::cout << std::format(...) << \"\\n\";\n
    #include <mp-units/systems/international.h>\n#include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n#include <format>\n#include <iostream>\n\n// ...\n\ninline constexpr struct horizontal_length final : quantity_spec<horizontal_length, isq::length> {} horizontal_length;\n\n// ...\n\nstd::cout << std::format(...) << \"\\n\";\n
    #include <mp-units/systems/international.h>\n#include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n#include <fmt/format.h>\n#include <iostream>\n\n// ...\n\ninline constexpr struct horizontal_length final : quantity_spec<horizontal_length, isq::length> {} horizontal_length;\n\n// ...\n\nstd::cout << fmt::format(...) << \"\\n\";\n
    #include <iostream>\n#include <mp-units/ext/format.h>\n#ifdef MP_UNITS_MODULES\n#include <mp-units/compat_macros.h>\nimport mp_units;\n#else\n#include <mp-units/systems/international.h>\n#include <mp-units/systems/isq.h>\n#include <mp-units/systems/si.h>\n#endif\n\n// ...\n\nQUANTITY_SPEC(horizontal_length, isq::length);\n\n// ...\n\nstd::cout << MP_UNITS_STD_FMT::format(...) << \"\\n\";\n

    Tip

    Depending on your preferences, you can either write:

    "},{"location":"users_guide/use_cases/wide_compatibility/#compatibility-macros","title":"Compatibility macros","text":"

    This chapter describes only the most essential tools the mp-units users need. All the compatibility macros can be found in the mp-units/compat_macros.h header file.

    Tip

    The mp-units/compat_macros.h header file is implicitly included when we use \"legacy\" headers in our translation units. However, it has to be explicitly included when we use C++20 modules, as those do not propagate preprocessor macros.

    "},{"location":"users_guide/use_cases/wide_compatibility/#QUANTITY_SPEC","title":"QUANTITY_SPEC(name, ...)","text":"

    Quantity specification definitions benefit from an explicit object parameter added in C++23 to remove the need for CRTP idiom, which significantly simplifies the code.

    This macro benefits from the new C++23 feature if available. Otherwise, it uses the CRTP idiom under the hood.

    "},{"location":"users_guide/use_cases/wide_compatibility/#mp_units_std_fmt","title":"MP_UNITS_STD_FMT","text":"

    Some of the supported compilers do not support std::format and related tools. Also, despite using a conformant compiler, some projects still choose to use fmtlib as their primary formatting facility (e.g., to benefit from additional features provided with the library).

    This macro resolves to either the std or fmt namespace, depending on the value of MP_UNITS_API_STD_FORMAT CMake option.

    To include the header files of the underlying text formatting framework, the following include should be used:

    #include <mp-units/ext/format.h>\n
    "},{"location":"users_guide/use_cases/wide_compatibility/#contracts","title":"Contracts","text":"

    The mp-units library internally does contract checking by default. It can be disabled with a Conan or CMake option. However, when enabled, it can use either gsl-lite or ms-gsl. To write a code that is independent from the underlying framework, the following preprocessor macros are exposed:

    Their meaning is consistent with respective gsl-lite.

    Also, to include the header files of the underlying framework, the following include should be used:

    #include <mp-units/ext/contracts.h>\n
    "},{"location":"users_guide/use_cases/working_with_legacy_interfaces/","title":"Working with Legacy interfaces","text":"

    In case we are working with a legacy/unsafe interface, we may need to extract the numerical value of a quantity and pass it to some third-party legacy unsafe interfaces.

    In such situations we can use .numerical_value_in(Unit) member function:

    void legacy_check_speed_limit(int speed_in_km_per_h);\n
    legacy_check_speed_limit((180 * km / (2 * h)).numerical_value_in(km / h));\n

    Such a getter will explicitly enforce the usage of a correct unit required by the underlying interface, which reduces a significant number of safety-related issues.

    The above code will not compile in case value truncation may happen. To solve the issue, we need to either use a value-preserving representation type or force the truncating conversion with .force_numerical_value_in(Unit):

    legacy_check_speed_limit((140 * mi / (2 * h)).force_numerical_value_in(km / h));\n

    The getters mentioned above always return by value as a quantity value conversion may be required to adjust it to the target unit. In case a user needs a reference to the underlying storage .numerical_value_ref_in(Unit) should be used:

    void legacy_set_speed_limit(int* speed_in_km_per_h) { *speed_in_km_per_h = 100; }\n
    quantity<km / h, int> speed_limit;\nlegacy_set_speed_limit(&speed_limit.numerical_value_ref_in(km / h));\n

    This member function again requires a target unit to enforce safety. This overload does not participate in overload resolution if the provided unit has a different scaling factor than the current one.

    "},{"location":"blog/archive/2025/","title":"2025","text":""},{"location":"blog/archive/2024/","title":"2024","text":""},{"location":"blog/archive/2023/","title":"2023","text":""},{"location":"blog/category/metrology/","title":"Metrology","text":""},{"location":"blog/category/wg21-updates/","title":"WG21 Updates","text":""},{"location":"blog/category/releases/","title":"Releases","text":""},{"location":"blog/page/2/","title":"Blog","text":""},{"location":"blog/archive/2024/page/2/","title":"2024","text":""}]} \ No newline at end of file diff --git a/HEAD/users_guide/framework_basics/systems_of_quantities/index.html b/HEAD/users_guide/framework_basics/systems_of_quantities/index.html index e7d40e0f..4e6f744b 100644 --- a/HEAD/users_guide/framework_basics/systems_of_quantities/index.html +++ b/HEAD/users_guide/framework_basics/systems_of_quantities/index.html @@ -2681,6 +2681,13 @@ the first common node in a hierarchy tree of the same kind. For example:

    static_assert(implicitly_convertible(isq::radius, isq::width)); static_assert(implicitly_convertible(isq::radius, isq::length)); +

    Implicit conversions are allowed on copy-initialization:

    +
    void foo(quantity<isq::length[m]> q);
+
    +
    quantity<isq::width[m]> q1 = 42 * m;
+quantity<isq::length[m]> q2 = q1;  // implicit quantity conversion
+foo(q1);                           // implicit quantity conversion
+

  • Explicit conversions

    @@ -2688,12 +2695,21 @@ the first common node in a hierarchy tree of the same kind. For example:

  • not every length is a width
  • not every width is a radius
    • -
    static_assert(!implicitly_convertible(isq::length, isq::width));
-static_assert(!implicitly_convertible(isq::width, isq::radius));
-static_assert(!implicitly_convertible(isq::length, isq::radius));
-static_assert(explicitly_convertible(isq::length, isq::width));
-static_assert(explicitly_convertible(isq::width, isq::radius));
-static_assert(explicitly_convertible(isq::length, isq::radius));
+
    static_assert(!implicitly_convertible(isq::length, isq::width));
+static_assert(!implicitly_convertible(isq::width, isq::radius));
+static_assert(!implicitly_convertible(isq::length, isq::radius));
+static_assert(explicitly_convertible(isq::length, isq::width));
+static_assert(explicitly_convertible(isq::width, isq::radius));
+static_assert(explicitly_convertible(isq::length, isq::radius));
+
    
+
    Explicit conversions are forced by passing the quantity to a call operator of a quantity_spec
+type or by calling quantity's explicit constructor:
    
+
    void foo(quantity<isq::height[m]> q);
+
    
+
    quantity<isq::length[m]> q1 = 42 * m;
+quantity<isq::height[m]> q2 = isq::height(q1);  // explicit quantity conversion
+quantity<isq::height[m]> q3(q1);                // direct initialization
+foo(isq::height(q1));                           // explicit quantity conversion
 
    
 
 
  • 
@@ -2702,9 +2718,16 @@ the first common node in a hierarchy tree of the same kind. For example:
    
 
  • height is not a width
    • 
 
  • both height and width are quantities of kind length
    • 
 
-
    static_assert(!implicitly_convertible(isq::height, isq::width));
-static_assert(!explicitly_convertible(isq::height, isq::width));
-static_assert(castable(isq::height, isq::width));
+
    static_assert(!implicitly_convertible(isq::height, isq::width));
+static_assert(!explicitly_convertible(isq::height, isq::width));
+static_assert(castable(isq::height, isq::width));
+
    
+
    Explicit casts are forced with a dedicated quantity_cast function:
    
+
    void foo(quantity<isq::height[m]> q);
+
    
+
    quantity<isq::width[m]> q1 = 42 * m;
+quantity<isq::height[m]> q2 = quantity_cast<isq::height>(q1);  // explicit quantity cast
+foo(quantity_cast<isq::height>(q1));                           // explicit quantity cast
 
    
 
 
  • 
@@ -2712,9 +2735,15 @@ the first common node in a hierarchy tree of the same kind. For example:
    
 
      
 
    • time has nothing in common with length
      • 
 
    
-
    static_assert(!implicitly_convertible(isq::time, isq::length));
-static_assert(!explicitly_convertible(isq::time, isq::length));
-static_assert(!castable(isq::time, isq::length));
+
    static_assert(!implicitly_convertible(isq::time, isq::length));
+static_assert(!explicitly_convertible(isq::time, isq::length));
+static_assert(!castable(isq::time, isq::length));
+
    
+
    Even the explicit casts will not force such a conversion:
    
+
    void foo(quantity<isq::length[m]>);
+
    
+
    quantity<isq::length[m]> q1 = 42 * s;    // Compile-time error
+foo(quantity_cast<isq::length>(42 * s)); // Compile-time error
 
    
 
    • 
 
@@ -2747,20 +2776,20 @@ that can be used to create them implicitly:
    
   and time. As those are also the roots of quantities of their kinds and all other quantities from their
   trees are implicitly convertible to them (we agreed on that "every width is a length" already),
   it means that an energy can be implicitly constructed from any quantity of mass, length, and time:
    
-
    static_assert(implicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time), isq::energy));
-static_assert(implicitly_convertible(isq::mass * pow<2>(isq::height) / pow<2>(isq::time), isq::energy));
+
    static_assert(implicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time), isq::energy));
+static_assert(implicitly_convertible(isq::mass * pow<2>(isq::height) / pow<2>(isq::time), isq::energy));
 
    
 
 
  • 
 
    mechanical energy is a more "specialized" quantity than energy (not every energy is
   a mechanical energy). It is why an explicit cast is needed to convert from either energy or
   the results of its quantity equation:
    
-
    static_assert(!implicitly_convertible(isq::energy, isq::mechanical_energy));
-static_assert(explicitly_convertible(isq::energy, isq::mechanical_energy));
-static_assert(!implicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time),
-                                      isq::mechanical_energy));
-static_assert(explicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time),
-                                     isq::mechanical_energy));
+
    static_assert(!implicitly_convertible(isq::energy, isq::mechanical_energy));
+static_assert(explicitly_convertible(isq::energy, isq::mechanical_energy));
+static_assert(!implicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time),
+                                      isq::mechanical_energy));
+static_assert(explicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time),
+                                     isq::mechanical_energy));
 
    
 
    • 
 
  • 
@@ -2769,14 +2798,14 @@ that can be used to create them implicitly:
    
   quantity equation. Maybe not every
   mass * pow<2>(length) / pow<2>(time) is a gravitational potential energy, but every
   mass * acceleration_of_free_fall * height is.
    
-
    static_assert(!implicitly_convertible(isq::energy, gravitational_potential_energy));
-static_assert(explicitly_convertible(isq::energy, gravitational_potential_energy));
-static_assert(!implicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time),
-                                      gravitational_potential_energy));
-static_assert(explicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time),
-                                     gravitational_potential_energy));
-static_assert(implicitly_convertible(isq::mass * isq::acceleration_of_free_fall * isq::height,
-                                     gravitational_potential_energy));
+
    static_assert(!implicitly_convertible(isq::energy, gravitational_potential_energy));
+static_assert(explicitly_convertible(isq::energy, gravitational_potential_energy));
+static_assert(!implicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time),
+                                      gravitational_potential_energy));
+static_assert(explicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time),
+                                     gravitational_potential_energy));
+static_assert(implicitly_convertible(isq::mass * isq::acceleration_of_free_fall * isq::height,
+                                     gravitational_potential_energy));
 
    
 
    • 
 
@@ -2793,16 +2822,16 @@ to type kind_of<isq::length>.
    
 
    
 
    Such an entity behaves as any quantity of its kind. This means that it is implicitly
 convertible to any quantity in a tree.
    
-
    static_assert(!implicitly_convertible(isq::length, isq::height));
-static_assert(implicitly_convertible(kind_of<isq::length>, isq::height));
+
    static_assert(!implicitly_convertible(isq::length, isq::height));
+static_assert(implicitly_convertible(kind_of<isq::length>, isq::height));
 
    
 
    Additionally, the result of operations on quantity kinds is also a quantity kind:
    
-
    static_assert(same_type<kind_of<isq::length> / kind_of<isq::time>, kind_of<isq::length / isq::time>>);
+
    static_assert(same_type<kind_of<isq::length> / kind_of<isq::time>, kind_of<isq::length / isq::time>>);
 
    
 
    However, if at least one equation's operand is not a quantity kind, the result becomes a "strong"
 quantity where all the kinds are converted to the hierarchy tree's root quantities:
    
-
    static_assert(!same_type<kind_of<isq::length> / isq::time, kind_of<isq::length / isq::time>>);
-static_assert(same_type<kind_of<isq::length> / isq::time, isq::length / isq::time>);
+
    static_assert(!same_type<kind_of<isq::length> / isq::time, kind_of<isq::length / isq::time>>);
+static_assert(same_type<kind_of<isq::length> / isq::time, isq::length / isq::time>);
 
    
 
    
 
    Info
    
@@ -2810,7 +2839,7 @@ quantity where all the kinds are converted to the hierarchy tree's root quantiti
 in the quantity_spec definition can be put as a template parameter to the kind_of
 specifier. For example, kind_of<isq::width> will fail to compile. However, we can call
 get_kind(q) to obtain a kind of any quantity:
    
-
    static_assert(get_kind(isq::width) == kind_of<isq::length>);
+
    static_assert(get_kind(isq::width) == kind_of<isq::length>);