diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 30a286f..389c6f9 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.6.7","generation_timestamp":"2023-12-11T01:07:56","documenter_version":"1.2.1"}} \ No newline at end of file +{"documenter":{"julia_version":"1.6.7","generation_timestamp":"2024-05-29T20:33:17","documenter_version":"1.4.1"}} \ No newline at end of file diff --git a/dev/assets/documenter.js b/dev/assets/documenter.js index f531160..c6562b5 100644 --- a/dev/assets/documenter.js +++ b/dev/assets/documenter.js @@ -4,7 +4,6 @@ requirejs.config({ 'highlight-julia': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/languages/julia.min', 'headroom': 'https://cdnjs.cloudflare.com/ajax/libs/headroom/0.12.0/headroom.min', 'jqueryui': 'https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.13.2/jquery-ui.min', - 'minisearch': 'https://cdn.jsdelivr.net/npm/minisearch@6.1.0/dist/umd/index.min', 'katex-auto-render': 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/contrib/auto-render.min', 'jquery': 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.0/jquery.min', 'headroom-jquery': 'https://cdnjs.cloudflare.com/ajax/libs/headroom/0.12.0/jQuery.headroom.min', @@ -103,9 +102,10 @@ $(document).on("click", ".docstring header", function () { }); }); -$(document).on("click", ".docs-article-toggle-button", function () { +$(document).on("click", ".docs-article-toggle-button", function (event) { let articleToggleTitle = "Expand docstring"; let navArticleToggleTitle = "Expand all docstrings"; + let animationSpeed = event.noToggleAnimation ? 0 : 400; debounce(() => { if (isExpanded) { @@ -116,7 +116,7 @@ $(document).on("click", ".docs-article-toggle-button", function () { isExpanded = false; - $(".docstring section").slideUp(); + $(".docstring section").slideUp(animationSpeed); } else { $(this).removeClass("fa-chevron-down").addClass("fa-chevron-up"); $(".docstring-article-toggle-button") @@ -127,7 +127,7 @@ $(document).on("click", ".docs-article-toggle-button", function () { articleToggleTitle = "Collapse docstring"; navArticleToggleTitle = "Collapse all docstrings"; - $(".docstring section").slideDown(); + $(".docstring section").slideDown(animationSpeed); } $(this).prop("title", navArticleToggleTitle); @@ -224,224 +224,465 @@ $(document).ready(function () { }) //////////////////////////////////////////////////////////////////////////////// -require(['jquery', 'minisearch'], function($, minisearch) { - -// In general, most search related things will have "search" as a prefix. -// To get an in-depth about the thought process you can refer: https://hetarth02.hashnode.dev/series/gsoc +require(['jquery'], function($) { -let results = []; -let timer = undefined; +$(document).ready(function () { + let meta = $("div[data-docstringscollapsed]").data(); -let data = documenterSearchIndex["docs"].map((x, key) => { - x["id"] = key; // minisearch requires a unique for each object - return x; + if (meta?.docstringscollapsed) { + $("#documenter-article-toggle-button").trigger({ + type: "click", + noToggleAnimation: true, + }); + } }); -// list below is the lunr 2.1.3 list minus the intersect with names(Base) -// (all, any, get, in, is, only, which) and (do, else, for, let, where, while, with) -// ideally we'd just filter the original list but it's not available as a variable -const stopWords = new Set([ - "a", - "able", - "about", - "across", - "after", - "almost", - "also", - "am", - "among", - "an", - "and", - "are", - "as", - "at", - "be", - "because", - "been", - "but", - "by", - "can", - "cannot", - "could", - "dear", - "did", - "does", - "either", - "ever", - "every", - "from", - "got", - "had", - "has", - "have", - "he", - "her", - "hers", - "him", - "his", - "how", - "however", - "i", - "if", - "into", - "it", - "its", - "just", - "least", - "like", - "likely", - "may", - "me", - "might", - "most", - "must", - "my", - "neither", - "no", - "nor", - "not", - "of", - "off", - "often", - "on", - "or", - "other", - "our", - "own", - "rather", - "said", - "say", - "says", - "she", - "should", - "since", - "so", - "some", - "than", - "that", - "the", - "their", - "them", - "then", - "there", - "these", - "they", - "this", - "tis", - "to", - "too", - "twas", - "us", - "wants", - "was", - "we", - "were", - "what", - "when", - "who", - "whom", - "why", - "will", - "would", - "yet", - "you", - "your", -]); - -let index = new minisearch({ - fields: ["title", "text"], // fields to index for full-text search - storeFields: ["location", "title", "text", "category", "page"], // fields to return with search results - processTerm: (term) => { - let word = stopWords.has(term) ? null : term; - if (word) { - // custom trimmer that doesn't strip @ and !, which are used in julia macro and function names - word = word - .replace(/^[^a-zA-Z0-9@!]+/, "") - .replace(/[^a-zA-Z0-9@!]+$/, ""); - } +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { - return word ?? null; - }, - // add . as a separator, because otherwise "title": "Documenter.Anchors.add!", would not find anything if searching for "add!", only for the entire qualification - tokenize: (string) => string.split(/[\s\-\.]+/), - // options which will be applied during the search - searchOptions: { - boost: { title: 100 }, - fuzzy: 2, +/* +To get an in-depth about the thought process you can refer: https://hetarth02.hashnode.dev/series/gsoc + +PSEUDOCODE: + +Searching happens automatically as the user types or adjusts the selected filters. +To preserve responsiveness, as much as possible of the slow parts of the search are done +in a web worker. Searching and result generation are done in the worker, and filtering and +DOM updates are done in the main thread. The filters are in the main thread as they should +be very quick to apply. This lets filters be changed without re-searching with minisearch +(which is possible even if filtering is on the worker thread) and also lets filters be +changed _while_ the worker is searching and without message passing (neither of which are +possible if filtering is on the worker thread) + +SEARCH WORKER: + +Import minisearch + +Build index + +On message from main thread + run search + find the first 200 unique results from each category, and compute their divs for display + note that this is necessary and sufficient information for the main thread to find the + first 200 unique results from any given filter set + post results to main thread + +MAIN: + +Launch worker + +Declare nonconstant globals (worker_is_running, last_search_text, unfiltered_results) + +On text update + if worker is not running, launch_search() + +launch_search + set worker_is_running to true, set last_search_text to the search text + post the search query to worker + +on message from worker + if last_search_text is not the same as the text in the search field, + the latest search result is not reflective of the latest search query, so update again + launch_search() + otherwise + set worker_is_running to false + + regardless, display the new search results to the user + save the unfiltered_results as a global + update_search() + +on filter click + adjust the filter selection + update_search() + +update_search + apply search filters by looping through the unfiltered_results and finding the first 200 + unique results that match the filters + + Update the DOM +*/ + +/////// SEARCH WORKER /////// + +function worker_function(documenterSearchIndex, documenterBaseURL, filters) { + importScripts( + "https://cdn.jsdelivr.net/npm/minisearch@6.1.0/dist/umd/index.min.js" + ); + + let data = documenterSearchIndex.map((x, key) => { + x["id"] = key; // minisearch requires a unique for each object + return x; + }); + + // list below is the lunr 2.1.3 list minus the intersect with names(Base) + // (all, any, get, in, is, only, which) and (do, else, for, let, where, while, with) + // ideally we'd just filter the original list but it's not available as a variable + const stopWords = new Set([ + "a", + "able", + "about", + "across", + "after", + "almost", + "also", + "am", + "among", + "an", + "and", + "are", + "as", + "at", + "be", + "because", + "been", + "but", + "by", + "can", + "cannot", + "could", + "dear", + "did", + "does", + "either", + "ever", + "every", + "from", + "got", + "had", + "has", + "have", + "he", + "her", + "hers", + "him", + "his", + "how", + "however", + "i", + "if", + "into", + "it", + "its", + "just", + "least", + "like", + "likely", + "may", + "me", + "might", + "most", + "must", + "my", + "neither", + "no", + "nor", + "not", + "of", + "off", + "often", + "on", + "or", + "other", + "our", + "own", + "rather", + "said", + "say", + "says", + "she", + "should", + "since", + "so", + "some", + "than", + "that", + "the", + "their", + "them", + "then", + "there", + "these", + "they", + "this", + "tis", + "to", + "too", + "twas", + "us", + "wants", + "was", + "we", + "were", + "what", + "when", + "who", + "whom", + "why", + "will", + "would", + "yet", + "you", + "your", + ]); + + let index = new MiniSearch({ + fields: ["title", "text"], // fields to index for full-text search + storeFields: ["location", "title", "text", "category", "page"], // fields to return with results processTerm: (term) => { let word = stopWords.has(term) ? null : term; if (word) { + // custom trimmer that doesn't strip @ and !, which are used in julia macro and function names word = word .replace(/^[^a-zA-Z0-9@!]+/, "") .replace(/[^a-zA-Z0-9@!]+$/, ""); + + word = word.toLowerCase(); } return word ?? null; }, + // add . as a separator, because otherwise "title": "Documenter.Anchors.add!", would not + // find anything if searching for "add!", only for the entire qualification tokenize: (string) => string.split(/[\s\-\.]+/), - }, -}); + // options which will be applied during the search + searchOptions: { + prefix: true, + boost: { title: 100 }, + fuzzy: 2, + }, + }); -index.addAll(data); + index.addAll(data); + + /** + * Used to map characters to HTML entities. + * Refer: https://github.com/lodash/lodash/blob/main/src/escape.ts + */ + const htmlEscapes = { + "&": "&", + "<": "<", + ">": ">", + '"': """, + "'": "'", + }; + + /** + * Used to match HTML entities and HTML characters. + * Refer: https://github.com/lodash/lodash/blob/main/src/escape.ts + */ + const reUnescapedHtml = /[&<>"']/g; + const reHasUnescapedHtml = RegExp(reUnescapedHtml.source); + + /** + * Escape function from lodash + * Refer: https://github.com/lodash/lodash/blob/main/src/escape.ts + */ + function escape(string) { + return string && reHasUnescapedHtml.test(string) + ? string.replace(reUnescapedHtml, (chr) => htmlEscapes[chr]) + : string || ""; + } -let filters = [...new Set(data.map((x) => x.category))]; -var modal_filters = make_modal_body_filters(filters); -var filter_results = []; + /** + * Make the result component given a minisearch result data object and the value + * of the search input as queryString. To view the result object structure, refer: + * https://lucaong.github.io/minisearch/modules/_minisearch_.html#searchresult + * + * @param {object} result + * @param {string} querystring + * @returns string + */ + function make_search_result(result, querystring) { + let search_divider = `
`; + let display_link = + result.location.slice(Math.max(0), Math.min(50, result.location.length)) + + (result.location.length > 30 ? "..." : ""); // To cut-off the link because it messes with the overflow of the whole div + + if (result.page !== "") { + display_link += ` (${result.page})`; + } -$(document).on("keyup", ".documenter-search-input", function (event) { - // Adding a debounce to prevent disruptions from super-speed typing! - debounce(() => update_search(filter_results), 300); + let textindex = new RegExp(`${querystring}`, "i").exec(result.text); + let text = + textindex !== null + ? result.text.slice( + Math.max(textindex.index - 100, 0), + Math.min( + textindex.index + querystring.length + 100, + result.text.length + ) + ) + : ""; // cut-off text before and after from the match + + text = text.length ? escape(text) : ""; + + let display_result = text.length + ? "..." + + text.replace( + new RegExp(`${escape(querystring)}`, "i"), // For first occurrence + '$&' + ) + + "..." + : ""; // highlights the match + + let in_code = false; + if (!["page", "section"].includes(result.category.toLowerCase())) { + in_code = true; + } + + // We encode the full url to escape some special characters which can lead to broken links + let result_div = ` + +
+
${escape(result.title)}
+
${result.category}
+
+

+ ${display_result} +

+
+ ${display_link} +
+ + ${search_divider} + `; + + return result_div; + } + + self.onmessage = function (e) { + let query = e.data; + let results = index.search(query, { + filter: (result) => { + // Only return relevant results + return result.score >= 1; + }, + }); + + // Pre-filter to deduplicate and limit to 200 per category to the extent + // possible without knowing what the filters are. + let filtered_results = []; + let counts = {}; + for (let filter of filters) { + counts[filter] = 0; + } + let present = {}; + + for (let result of results) { + cat = result.category; + cnt = counts[cat]; + if (cnt < 200) { + id = cat + "---" + result.location; + if (present[id]) { + continue; + } + present[id] = true; + filtered_results.push({ + location: result.location, + category: cat, + div: make_search_result(result, query), + }); + } + } + + postMessage(filtered_results); + }; +} + +// `worker = Threads.@spawn worker_function(documenterSearchIndex)`, but in JavaScript! +const filters = [ + ...new Set(documenterSearchIndex["docs"].map((x) => x.category)), +]; +const worker_str = + "(" + + worker_function.toString() + + ")(" + + JSON.stringify(documenterSearchIndex["docs"]) + + "," + + JSON.stringify(documenterBaseURL) + + "," + + JSON.stringify(filters) + + ")"; +const worker_blob = new Blob([worker_str], { type: "text/javascript" }); +const worker = new Worker(URL.createObjectURL(worker_blob)); + +/////// SEARCH MAIN /////// + +// Whether the worker is currently handling a search. This is a boolean +// as the worker only ever handles 1 or 0 searches at a time. +var worker_is_running = false; + +// The last search text that was sent to the worker. This is used to determine +// if the worker should be launched again when it reports back results. +var last_search_text = ""; + +// The results of the last search. This, in combination with the state of the filters +// in the DOM, is used compute the results to display on calls to update_search. +var unfiltered_results = []; + +// Which filter is currently selected +var selected_filter = ""; + +$(document).on("input", ".documenter-search-input", function (event) { + if (!worker_is_running) { + launch_search(); + } }); +function launch_search() { + worker_is_running = true; + last_search_text = $(".documenter-search-input").val(); + worker.postMessage(last_search_text); +} + +worker.onmessage = function (e) { + if (last_search_text !== $(".documenter-search-input").val()) { + launch_search(); + } else { + worker_is_running = false; + } + + unfiltered_results = e.data; + update_search(); +}; + $(document).on("click", ".search-filter", function () { if ($(this).hasClass("search-filter-selected")) { - $(this).removeClass("search-filter-selected"); + selected_filter = ""; } else { - $(this).addClass("search-filter-selected"); + selected_filter = $(this).text().toLowerCase(); } - // Adding a debounce to prevent disruptions from crazy clicking! - debounce(() => get_filters(), 300); + // This updates search results and toggles classes for UI: + update_search(); }); -/** - * A debounce function, takes a function and an optional timeout in milliseconds - * - * @function callback - * @param {number} timeout - */ -function debounce(callback, timeout = 300) { - clearTimeout(timer); - timer = setTimeout(callback, timeout); -} - /** * Make/Update the search component - * - * @param {string[]} selected_filters */ -function update_search(selected_filters = []) { - let initial_search_body = ` -
Type something to get started!
- `; - +function update_search() { let querystring = $(".documenter-search-input").val(); if (querystring.trim()) { - results = index.search(querystring, { - filter: (result) => { - // Filtering results - if (selected_filters.length === 0) { - return result.score >= 1; - } else { - return ( - result.score >= 1 && selected_filters.includes(result.category) - ); - } - }, - }); + if (selected_filter == "") { + results = unfiltered_results; + } else { + results = unfiltered_results.filter((result) => { + return selected_filter == result.category.toLowerCase(); + }); + } let search_result_container = ``; + let modal_filters = make_modal_body_filters(); let search_divider = `
`; if (results.length) { @@ -449,19 +690,23 @@ function update_search(selected_filters = []) { let count = 0; let search_results = ""; - results.forEach(function (result) { - if (result.location) { - // Checking for duplication of results for the same page - if (!links.includes(result.location)) { - search_results += make_search_result(result, querystring); - count++; - } - + for (var i = 0, n = results.length; i < n && count < 200; ++i) { + let result = results[i]; + if (result.location && !links.includes(result.location)) { + search_results += result.div; + count++; links.push(result.location); } - }); + } - let result_count = `
${count} result(s)
`; + if (count == 1) { + count_str = "1 result"; + } else if (count == 200) { + count_str = "200+ results"; + } else { + count_str = count + " results"; + } + let result_count = `
${count_str}
`; search_result_container = `
@@ -490,125 +735,37 @@ function update_search(selected_filters = []) { $(".search-modal-card-body").html(search_result_container); } else { - filter_results = []; - modal_filters = make_modal_body_filters(filters, filter_results); - if (!$(".search-modal-card-body").hasClass("is-justify-content-center")) { $(".search-modal-card-body").addClass("is-justify-content-center"); } - $(".search-modal-card-body").html(initial_search_body); + $(".search-modal-card-body").html(` +
Type something to get started!
+ `); } } /** * Make the modal filter html * - * @param {string[]} filters - * @param {string[]} selected_filters * @returns string */ -function make_modal_body_filters(filters, selected_filters = []) { - let str = ``; - - filters.forEach((val) => { - if (selected_filters.includes(val)) { - str += `${val}`; - } else { - str += `${val}`; - } - }); +function make_modal_body_filters() { + let str = filters + .map((val) => { + if (selected_filter == val.toLowerCase()) { + return `${val}`; + } else { + return `${val}`; + } + }) + .join(""); - let filter_html = ` + return `
Filters: ${str} -
- `; - - return filter_html; -} - -/** - * Make the result component given a minisearch result data object and the value of the search input as queryString. - * To view the result object structure, refer: https://lucaong.github.io/minisearch/modules/_minisearch_.html#searchresult - * - * @param {object} result - * @param {string} querystring - * @returns string - */ -function make_search_result(result, querystring) { - let search_divider = `
`; - let display_link = - result.location.slice(Math.max(0), Math.min(50, result.location.length)) + - (result.location.length > 30 ? "..." : ""); // To cut-off the link because it messes with the overflow of the whole div - - if (result.page !== "") { - display_link += ` (${result.page})`; - } - - let textindex = new RegExp(`\\b${querystring}\\b`, "i").exec(result.text); - let text = - textindex !== null - ? result.text.slice( - Math.max(textindex.index - 100, 0), - Math.min( - textindex.index + querystring.length + 100, - result.text.length - ) - ) - : ""; // cut-off text before and after from the match - - let display_result = text.length - ? "..." + - text.replace( - new RegExp(`\\b${querystring}\\b`, "i"), // For first occurrence - '$&' - ) + - "..." - : ""; // highlights the match - - let in_code = false; - if (!["page", "section"].includes(result.category.toLowerCase())) { - in_code = true; - } - - // We encode the full url to escape some special characters which can lead to broken links - let result_div = ` - -
-
${result.title}
-
${result.category}
-
-

- ${display_result} -

-
- ${display_link} -
- - ${search_divider} - `; - - return result_div; -} - -/** - * Get selected filters, remake the filter html and lastly update the search modal - */ -function get_filters() { - let ele = $(".search-filters .search-filter-selected").get(); - filter_results = ele.map((x) => $(x).text().toLowerCase()); - modal_filters = make_modal_body_filters(filters, filter_results); - update_search(filter_results); +
`; } }) @@ -635,103 +792,107 @@ $(document).ready(function () { //////////////////////////////////////////////////////////////////////////////// require(['jquery'], function($) { -let search_modal_header = ` -
-
-

- - - - -

-
-
- -
-
-`; - -let initial_search_body = ` -
Type something to get started!
-`; - -let search_modal_footer = ` - -`; - -$(document.body).append( - ` - +10.52000000000001°

The functions in Base that are currently extended to accept units as their first argument and return values with those units are:

diff --git a/dev/guide/derived/index.html b/dev/guide/derived/index.html index 681a8ed..f1dba91 100644 --- a/dev/guide/derived/index.html +++ b/dev/guide/derived/index.html @@ -1,5 +1,5 @@ -Derived dimensions · DimensionfulAngles
GitHub

Derived dimensions

DimensionfulAngles.jl also defines derived dimensions that include angle. These are:

This allows, among other things, dispatching on these derived dimensions.

Several units are defined for these derived dimensions, including the steradian for solid angle and RPM for angular velocity.

DimensionfulAngles.jl also provides Periodic a UnitfulEquivalences.jl Equivalence to convert between period, frequency, and angular frequency of a periodic response.

Solid Angle

Solid angle is a two-dimensional angle subtended at a point. In the SI system it has units of $m²/m²=1$ and is non-dimensional. Here, following several proposed systems, it has dimensions of angle squared, 𝐀². See Relation to proposed SI extensions. The SI unit of solid angle is the steradian, which here is defined as $sr=rad²$. The steradian takes SI prefixes and therefore defines many other units (e.g., the millisteradian DimensionfulAngles.msrᵃ). These are documented in Prefixed units.

DimensionfulAngles.SolidAngle — Type
DimensionfulAngles.SolidAngle{T, U}

A supertype for quantities and levels of dimension 𝐀 * 𝐀 with a value of type T and units U.

See also: Unitful.Quantity, Unitful.Level.

source
DimensionfulAngles.srᵃ — Constant
srᵃ

The steradian, a unit of spherical angle.

There are 4π sr in a sphere. The steradian is the SI unit of solid angle. Unlike Unitful.sr, which follows SI and is therefor dimensionless, srᵃ has dimensions of Angle squared. Accepts SI prefixes.

Dimension: 𝐀²."

source

Luminous flux and illuminance

Luminous flux is a measure of perceived power of light and has dimensions of $𝐉*𝐀²$. The SI unit lumen (lm) = candela x steradian is provided as DimensionfulAngles.lmᵃ.

Illuminance is luminous flux per unit surface area and has dimensions of $𝐉*𝐀²*𝐋⁻²$. The SI unit lux (lx) = lumen / meter^2 is provided as DimensionfulAngles.lxᵃ.

DimensionfulAngles.LuminousFlux — Type
DimensionfulAngles.LuminousFlux{T, U}

A supertype for quantities and levels of dimension 𝐉 * 𝐀 ^ 2 with a value of type T and units U.

See also: Unitful.Quantity, Unitful.Level.

source
DimensionfulAngles.Illuminance — Type
DimensionfulAngles.Illuminance{T, U}

A supertype for quantities and levels of dimension 𝐉 * 𝐀 ^ 2 * 𝐋 ^ -2 with a value of type T and units U.

See also: Unitful.Quantity, Unitful.Level.

source
DimensionfulAngles.lmᵃ — Constant
lmᵃ

The lumen, an SI unit of luminous flux.

Defined as 1 cd × sr. Accepts SI prefixes.

Dimension: 𝐉𝐀²."

source
DimensionfulAngles.lxᵃ — Constant
lxᵃ

The lux, an SI unit of illuminance.

Defined as 1 lm / m^2. Accepts SI prefixes.

Dimension: 𝐉𝐀²𝐋⁻²."

source

Angular velocity and acceleration

Angular velocity has dimensions of angle over time 𝐀/𝐓 and can be used to measure different quantities such as rotational velocity, rotational speed, and angular frequency of a phase angle. Two units of angular velocity are defined: the revolutions per second (RPS) and the revolutions per minute (RPM), provided as DimensionfulAngles.rpsᵃ and DimensionfulAngles.rpmᵃ respectively.

Angular acceleration is the time rate of change of angular velocity and has dimensions of angle over time squared 𝐀/𝐓². No units are defined specifically for this derived dimension.

See also: Periodic.

DimensionfulAngles.AngularVelocity — Type
DimensionfulAngles.AngularVelocity{T, U}

A supertype for quantities and levels of dimension 𝐀 * 𝐓 ^ -1 with a value of type T and units U.

See also: Unitful.Quantity, Unitful.Level.

source
DimensionfulAngles.AngularAcceleration — Type
DimensionfulAngles.AngularAcceleration{T, U}

A supertype for quantities and levels of dimension 𝐀 * 𝐓 ^ -2 with a value of type T and units U.

See also: Unitful.Quantity, Unitful.Level.

source
DimensionfulAngles.rpsᵃ — Constant
rpsᵃ

Revolutions per second, a unit of angular velocity defined as 2π rad / s.

This differs from Unitful.rps in that it contains units of angle. Does not accepts SI prefixes.

Dimension: 𝐀 𝐓⁻¹.

See also DimensionfulAngles.radᵃ.

source
DimensionfulAngles.rpmᵃ — Constant
rpmᵃ

Revolutions per minute, a unit of angular velocity defined as 2π rad / minute.

This differs from Unitful.rpm in that it contains units of angle. Does not accepts SI prefixes.

Dimension: 𝐀 𝐓⁻¹.

See also DimensionfulAngles.radᵃ.

source

Angular period, wavenumber, and wavelength

Angular wavenumber has dimensions of angle over length 𝐀/𝐋 and is the spatial analogue of (temporal) angular frequency. It is used to describe responses that are periodic in space.

The angular period (dimensions of time over angle, 𝐓/𝐀) and angular wavelength (𝐋/𝐀) are define as the reciprocal of angular frequency and angular wavenumber, respectively.

No units are defined specifically for these derived dimensions.

See also: Periodic.

DimensionfulAngles.AngularWavelength — Type
DimensionfulAngles.AngularWavelength{T, U}

A supertype for quantities and levels of dimension 𝐋 * 𝐀 ^ -1 with a value of type T and units U.

See also: Unitful.Quantity, Unitful.Level.

source
DimensionfulAngles.AngularPeriod — Type
DimensionfulAngles.AngularPeriod{T, U}

A supertype for quantities and levels of dimension 𝐓 * 𝐀 ^ -1 with a value of type T and units U.

See also: Unitful.Quantity, Unitful.Level.

source
DimensionfulAngles.AngularWavenumber — Type
DimensionfulAngles.AngularWavenumber{T, U}

A supertype for quantities and levels of dimension 𝐀 * 𝐋 ^ -1 with a value of type T and units U.

See also: Unitful.Quantity, Unitful.Level.

source

Periodic and Dispersion equivalences

For periodic responses there are several analogous ways to measure the repeat period: period T (𝐓, s), frequency f (1/𝐓, Hz=1/s), or angular frequency ω (𝐀/𝐓, rad/s). These are related by

$f = 1/T = ω/2π$.

Analogously, spatial period and frequency are related by

$ν = 1/λ = k/2π$

between wavelength λ (𝐋, m), wavenumber ν (1/𝐋, 1/m), and angular wavenumber k (𝐀/𝐋, rad/m). Additionally an angular period and angular wavelength can be defined analogously as the reciprocal of angular frequency and angular wavenumber.

Diagram showing graphically the relationships between the various properties of harmonic waves: frequency, period, wavelength, angular frequency, and wavenumber.
image-source: Waldir, CC BY-SA 4.0 https://creativecommons.org/licenses/by-sa/4.0, via Wikimedia Commons

DimensionfulAngles.jl provides Periodic, a UnitfulEquivalences.jl Equivalence to convert between temporal or spatial period, frequency, angular frequency, and angular period of a periodic response.

It also provides Dispersion, which extends Periodic to convert between temporal and spatial values using a specific dispersion relation (or equivalently a phase velocity as used in the image above)).

DimensionfulAngles.Periodic — Type
Periodic()

Equivalence to convert between temporal or spatial period, frequency, angular frequency, and angular period.

These quantities are related by $f = ω/2π = 1/T = 1/(2πT̅)$, where

  • $f$ is the (temporal) frequency,
  • $ω$ is the (temporal) angular frequency,
  • $T$ is the (temporal) period,
  • $T̄$ is the (temporal) angular period,

and $ν = k/2π = 1/λ = 1/(2πλ̄)$, where

  • $ν$ is the (spatial) frequency (linear wavenumber),
  • $k$ is the (spatial) angular frequency (angular wavenumber),
  • $λ$ is the (spatial) period (linear wavelength), and
  • $λ̄$ is the (spatial) angular period (angular wavelength).

See also DimensionfulAngles.Dispersion

Example

julia> using Unitful
+Derived dimensions · DimensionfulAngles
GitHub
Derived dimensions
DimensionfulAngles.jl also defines derived dimensions that include angle. These are:
This allows, among other things, dispatching on these derived dimensions.
Several units are defined for these derived dimensions, including the steradian for solid angle and RPM for angular velocity.
DimensionfulAngles.jl also provides Periodic a UnitfulEquivalences.jl Equivalence to convert between period, frequency, and angular frequency of a periodic response.
Solid Angle
Solid angle is a two-dimensional angle subtended at a point. In the SI system it has units of $m²/m²=1$ and is non-dimensional. Here, following several proposed systems, it has dimensions of angle squared, 𝐀². See Relation to proposed SI extensions. The SI unit of solid angle is the steradian, which here is defined as $sr=rad²$. The steradian takes SI prefixes and therefore defines many other units (e.g., the millisteradian DimensionfulAngles.msrᵃ). These are documented in Prefixed units.
DimensionfulAngles.SolidAngle — Type
DimensionfulAngles.SolidAngle{T, U}
A supertype for quantities and levels of dimension 𝐀 * 𝐀 with a value of type T and units U.
See also: Unitful.Quantity, Unitful.Level.
source
DimensionfulAngles.srᵃ — Constant
srᵃ
The steradian, a unit of spherical angle.
There are 4π sr in a sphere. The steradian is the SI unit of solid angle. Unlike Unitful.sr, which follows SI and is therefor dimensionless, srᵃ has dimensions of Angle squared. Accepts SI prefixes.
Dimension: 𝐀²."
source
Luminous flux and illuminance
Luminous flux is a measure of perceived power of light and has dimensions of $𝐉*𝐀²$. The SI unit lumen (lm) = candela x steradian is provided as DimensionfulAngles.lmᵃ.
Illuminance is luminous flux per unit surface area and has dimensions of $𝐉*𝐀²*𝐋⁻²$. The SI unit lux (lx) = lumen / meter^2 is provided as DimensionfulAngles.lxᵃ.
DimensionfulAngles.LuminousFlux — Type
DimensionfulAngles.LuminousFlux{T, U}
A supertype for quantities and levels of dimension 𝐉 * 𝐀 ^ 2 with a value of type T and units U.
See also: Unitful.Quantity, Unitful.Level.
source
DimensionfulAngles.Illuminance — Type
DimensionfulAngles.Illuminance{T, U}
A supertype for quantities and levels of dimension 𝐉 * 𝐀 ^ 2 * 𝐋 ^ -2 with a value of type T and units U.
See also: Unitful.Quantity, Unitful.Level.
source
DimensionfulAngles.lmᵃ — Constant
lmᵃ
The lumen, an SI unit of luminous flux.
Defined as 1 cd × sr. Accepts SI prefixes.
Dimension: 𝐉𝐀²."
source
DimensionfulAngles.lxᵃ — Constant
lxᵃ
The lux, an SI unit of illuminance.
Defined as 1 lm / m^2. Accepts SI prefixes.
Dimension: 𝐉𝐀²𝐋⁻²."
source
Angular velocity and acceleration
Angular velocity has dimensions of angle over time 𝐀/𝐓 and can be used to measure different quantities such as rotational velocity, rotational speed, and angular frequency of a phase angle. Two units of angular velocity are defined: the revolutions per second (RPS) and the revolutions per minute (RPM), provided as DimensionfulAngles.rpsᵃ and DimensionfulAngles.rpmᵃ respectively.
Angular acceleration is the time rate of change of angular velocity and has dimensions of angle over time squared 𝐀/𝐓². No units are defined specifically for this derived dimension.
See also: Periodic.
DimensionfulAngles.AngularVelocity — Type
DimensionfulAngles.AngularVelocity{T, U}
A supertype for quantities and levels of dimension 𝐀 * 𝐓 ^ -1 with a value of type T and units U.
See also: Unitful.Quantity, Unitful.Level.
source
DimensionfulAngles.AngularAcceleration — Type
DimensionfulAngles.AngularAcceleration{T, U}
A supertype for quantities and levels of dimension 𝐀 * 𝐓 ^ -2 with a value of type T and units U.
See also: Unitful.Quantity, Unitful.Level.
source
DimensionfulAngles.rpsᵃ — Constant
rpsᵃ
Revolutions per second, a unit of angular velocity defined as 2π rad / s.
This differs from Unitful.rps in that it contains units of angle. Does not accepts SI prefixes.
Dimension: 𝐀 𝐓⁻¹.
See also DimensionfulAngles.radᵃ.
source
DimensionfulAngles.rpmᵃ — Constant
rpmᵃ
Revolutions per minute, a unit of angular velocity defined as 2π rad / minute.
This differs from Unitful.rpm in that it contains units of angle. Does not accepts SI prefixes.
Dimension: 𝐀 𝐓⁻¹.
See also DimensionfulAngles.radᵃ.
source
Angular period, wavenumber, and wavelength
Angular wavenumber has dimensions of angle over length 𝐀/𝐋 and is the spatial analogue of (temporal) angular frequency. It is used to describe responses that are periodic in space.
The angular period (dimensions of time over angle, 𝐓/𝐀) and angular wavelength (𝐋/𝐀) are define as the reciprocal of angular frequency and angular wavenumber, respectively.
No units are defined specifically for these derived dimensions.
See also: Periodic.
DimensionfulAngles.AngularWavelength — Type
DimensionfulAngles.AngularWavelength{T, U}
A supertype for quantities and levels of dimension 𝐋 * 𝐀 ^ -1 with a value of type T and units U.
See also: Unitful.Quantity, Unitful.Level.
source
DimensionfulAngles.AngularPeriod — Type
DimensionfulAngles.AngularPeriod{T, U}
A supertype for quantities and levels of dimension 𝐓 * 𝐀 ^ -1 with a value of type T and units U.
See also: Unitful.Quantity, Unitful.Level.
source
DimensionfulAngles.AngularWavenumber — Type
DimensionfulAngles.AngularWavenumber{T, U}
A supertype for quantities and levels of dimension 𝐀 * 𝐋 ^ -1 with a value of type T and units U.
See also: Unitful.Quantity, Unitful.Level.
source
Periodic and Dispersion equivalences
For periodic responses there are several analogous ways to measure the repeat period: period T (𝐓, s), frequency f (1/𝐓, Hz=1/s), or angular frequency ω (𝐀/𝐓, rad/s). These are related by
$f = 1/T = ω/2π$.
Analogously, spatial period and frequency are related by
$ν = 1/λ = k/2π$
between wavelength λ (𝐋, m), wavenumber ν (1/𝐋, 1/m), and angular wavenumber k (𝐀/𝐋, rad/m). Additionally an angular period and angular wavelength can be defined analogously as the reciprocal of angular frequency and angular wavenumber.
Diagram showing graphically the relationships between the various properties of harmonic waves: frequency, period, wavelength, angular frequency, and wavenumber.
image-source: Waldir, CC BY-SA 4.0 https://creativecommons.org/licenses/by-sa/4.0, via Wikimedia Commons
DimensionfulAngles.jl provides Periodic, a UnitfulEquivalences.jl Equivalence to convert between temporal or spatial period, frequency, angular frequency, and angular period of a periodic response.
It also provides Dispersion, which extends Periodic to convert between temporal and spatial values using a specific dispersion relation (or equivalently a phase velocity as used in the image above)).
DimensionfulAngles.Periodic — Type
Periodic()
Equivalence to convert between temporal or spatial period, frequency, angular frequency, and angular period.
These quantities are related by $f = ω/2π = 1/T = 1/(2πT̅)$, where
  • $f$ is the (temporal) frequency,
  • $ω$ is the (temporal) angular frequency,
  • $T$ is the (temporal) period,
  • $T̄$ is the (temporal) angular period,
and $ν = k/2π = 1/λ = 1/(2πλ̄)$, where
  • $ν$ is the (spatial) frequency (linear wavenumber),
  • $k$ is the (spatial) angular frequency (angular wavenumber),
  • $λ$ is the (spatial) period (linear wavelength), and
  • $λ̄$ is the (spatial) angular period (angular wavelength).
See also DimensionfulAngles.Dispersion
Example
julia> using Unitful
 
 julia> using DimensionfulAngles
 
@@ -7,7 +7,7 @@
 0.1 s
 
 julia> uconvert(u"radᵃ/s", 1u"Hz", Periodic())
-6.283185307179586 rad s⁻¹
source
DimensionfulAngles.Dispersion — Type
Dispersion(; dispersion=nothing, dispersion_inverse=nothing)
Equivalence to convert between temporal and spatial frequencies using a specific dispersion relation.
This extends the Periodic() equivalence to convert between spatial and temporal quantities based on the provided dispersion relation.
See also DimensionfulAngles.Periodic.
Example
julia> using DimensionfulAngles, Unitful
+6.283185307179586 rad s⁻¹
source
DimensionfulAngles.Dispersion — Type
Dispersion(; dispersion=nothing, dispersion_inverse=nothing)
Equivalence to convert between temporal and spatial frequencies using a specific dispersion relation.
This extends the Periodic() equivalence to convert between spatial and temporal quantities based on the provided dispersion relation.
See also DimensionfulAngles.Periodic.
Example
julia> using DimensionfulAngles, Unitful
 
 julia> g = Unitful.gn  # gravitational acceleration
 9.80665 m s⁻²
@@ -45,4 +45,4 @@
        );
 
 julia> uconvert(u"Hz", 0.004025678249387654u"radᵃ/mm", waterwaves) ≈ 1u"Hz"
-true
source
Syntax
Contents:
Syntax provided by Unitful.jl
DimensionfulAngles.SolidAngleUnits — Type
DimensionfulAngles.SolidAngleUnits{U}
A supertype for units of dimension 𝐀 * 𝐀. Equivalent to Unitful.Units{U, 𝐀 * 𝐀}.
See also: Unitful.Units.
source
DimensionfulAngles.AngularPeriodUnits — Type
DimensionfulAngles.AngularPeriodUnits{U}
A supertype for units of dimension 𝐓 * 𝐀 ^ -1. Equivalent to Unitful.Units{U, 𝐓 * 𝐀 ^ -1}.
See also: Unitful.Units.
source
DimensionfulAngles.LuminousFluxUnits — Type
DimensionfulAngles.LuminousFluxUnits{U}
A supertype for units of dimension 𝐉 * 𝐀 ^ 2. Equivalent to Unitful.Units{U, 𝐉 * 𝐀 ^ 2}.
See also: Unitful.Units.
source
DimensionfulAngles.IlluminanceUnits — Type
DimensionfulAngles.IlluminanceUnits{U}
A supertype for units of dimension 𝐉 * 𝐀 ^ 2 * 𝐋 ^ -2. Equivalent to Unitful.Units{U, 𝐉 * 𝐀 ^ 2 * 𝐋 ^ -2}.
See also: Unitful.Units.
source
DimensionfulAngles.IlluminanceFreeUnits — Type
DimensionfulAngles.IlluminanceFreeUnits{U}
A supertype for Unitful.FreeUnits of dimension 𝐉 * 𝐀 ^ 2 * 𝐋 ^ -2. Equivalent to Unitful.FreeUnits{U, 𝐉 * 𝐀 ^ 2 * 𝐋 ^ -2}.
source
Prefixed Units

+true
source

Syntax

Contents:

Syntax provided by Unitful.jl

DimensionfulAngles.SolidAngleUnits — Type
DimensionfulAngles.SolidAngleUnits{U}

A supertype for units of dimension 𝐀 * 𝐀. Equivalent to Unitful.Units{U, 𝐀 * 𝐀}.

See also: Unitful.Units.

source
DimensionfulAngles.AngularPeriodUnits — Type
DimensionfulAngles.AngularPeriodUnits{U}

A supertype for units of dimension 𝐓 * 𝐀 ^ -1. Equivalent to Unitful.Units{U, 𝐓 * 𝐀 ^ -1}.

See also: Unitful.Units.

source
DimensionfulAngles.LuminousFluxUnits — Type
DimensionfulAngles.LuminousFluxUnits{U}

A supertype for units of dimension 𝐉 * 𝐀 ^ 2. Equivalent to Unitful.Units{U, 𝐉 * 𝐀 ^ 2}.

See also: Unitful.Units.

source
DimensionfulAngles.IlluminanceUnits — Type
DimensionfulAngles.IlluminanceUnits{U}

A supertype for units of dimension 𝐉 * 𝐀 ^ 2 * 𝐋 ^ -2. Equivalent to Unitful.Units{U, 𝐉 * 𝐀 ^ 2 * 𝐋 ^ -2}.

See also: Unitful.Units.

source
DimensionfulAngles.IlluminanceFreeUnits — Type
DimensionfulAngles.IlluminanceFreeUnits{U}

A supertype for Unitful.FreeUnits of dimension 𝐉 * 𝐀 ^ 2 * 𝐋 ^ -2. Equivalent to Unitful.FreeUnits{U, 𝐉 * 𝐀 ^ 2 * 𝐋 ^ -2}.

source

Prefixed Units

diff --git a/dev/guide/intro/index.html b/dev/guide/intro/index.html index e2de020..9943736 100644 --- a/dev/guide/intro/index.html +++ b/dev/guide/intro/index.html @@ -54,7 +54,7 @@ 𝐓⁻¹ julia> dimension(uconvert(:DimensionfulAngles, ω̄)) -𝐀 𝐓⁻¹source

Note that astronomical units in DimensionfulAngles and UnitfulAngles are not equivalent and quantities containing these units are converted to compatible, non-astronomical, units first. Specifically, the UnitfulAngles units [mas, μas, pas] are converted to arcsecond, the DimensionfulAngles unit asᵃ and all its prefixed versions are converted to arcsecondᵃ, and the DimensionfulAngles units [ʰᵃ, ᵐᵃ, ˢᵃ] are converted to hourAngleᵃ. For example:

julia> θ = 1u"μas"
+𝐀 𝐓⁻¹
source

Note that astronomical units in DimensionfulAngles and UnitfulAngles are not equivalent and quantities containing these units are converted to compatible, non-astronomical, units first. Specifically, the UnitfulAngles units [mas, μas, pas] are converted to arcsecond, the DimensionfulAngles unit asᵃ and all its prefixed versions are converted to arcsecondᵃ, and the DimensionfulAngles units [ʰᵃ, ᵐᵃ, ˢᵃ] are converted to hourAngleᵃ. For example:

julia> θ = 1u"μas"
 1 μas
 
 julia> θ̄ = uconvert(:DimensionfulAngles, θ)
@@ -70,13 +70,13 @@
 0.9825467074800567 rad
 
 julia> cos(45ua"°")
-0.7071067811865476
source
DimensionfulAngles.𝐀 — Constant
𝐀

A dimension representing Angle.

Not SI

Angle is not an SI base dimension.

source
DimensionfulAngles.radᵃ — Constant
radᵃ

The radian, a unit of angle.

There are 2π rad in a circle. The radian is the SI unit of angle. Unlike Unitful.rad, which follows SI and is therefor dimensionless, radᵃ has dimensions of Angle. Accepts SI prefixes.

Dimension: DimensionfulAngles.𝐀.

Examples

julia> using DimensionfulAngles
+0.7071067811865476
source
DimensionfulAngles.𝐀 — Constant
𝐀

A dimension representing Angle.

Not SI

Angle is not an SI base dimension.

source
DimensionfulAngles.radᵃ — Constant
radᵃ

The radian, a unit of angle.

There are 2π rad in a circle. The radian is the SI unit of angle. Unlike Unitful.rad, which follows SI and is therefor dimensionless, radᵃ has dimensions of Angle. Accepts SI prefixes.

Dimension: DimensionfulAngles.𝐀.

Examples

julia> using DimensionfulAngles
 
 julia> 1.0ua"rad" + 20.0ua"mrad"
-1.02 rad
source
DimensionfulAngles.°ᵃ — Constant
°ᵃ

The degree, a unit of angle.

There are 360° in a circle. The degree is an SI-accepted unit of angle. Unlike Unitful.°, which follows SI and is therefor dimensionless, °ᵃ has dimensions of Angle. Does not accepts SI prefixes.

Dimension: DimensionfulAngles.𝐀.

Examples

julia> using DimensionfulAngles
+1.02 rad
source
DimensionfulAngles.°ᵃ — Constant
°ᵃ

The degree, a unit of angle.

There are 360° in a circle. The degree is an SI-accepted unit of angle. Unlike Unitful.°, which follows SI and is therefor dimensionless, °ᵃ has dimensions of Angle. Does not accepts SI prefixes.

Dimension: DimensionfulAngles.𝐀.

Examples

julia> using DimensionfulAngles
 
 julia> 1ua"°"
-1°
source
DimensionfulAngles.θ₀ — Constant
θ₀

A quantity equal to the central angle of a plane circular sector whose arc length is equal to that of its radius. It has a value of exactly 1 rad or approximately 57.2958°. Used as the defining constant of Angle dimension in several proposed SI extension systems.

Dimensions: 𝐀.

See also DimensionfulAngles.radᵃ.

Examples

julia> using DimensionfulAngles
+1°
source
DimensionfulAngles.θ₀ — Constant
θ₀

A quantity equal to the central angle of a plane circular sector whose arc length is equal to that of its radius. It has a value of exactly 1 rad or approximately 57.2958°. Used as the defining constant of Angle dimension in several proposed SI extension systems.

Dimensions: 𝐀.

See also DimensionfulAngles.radᵃ.

Examples

julia> using DimensionfulAngles
 
 julia> θ₀
 1//1 rad
@@ -85,10 +85,10 @@
 57.29577951308232°
 
 julia> 2.1ua"rad" / θ₀
-2.1
source
DimensionfulAngles.@ua_str — Macro
macro ua_str(unit)

String macro to easily recall units with angular dimension located in the DimensionfulAngles package. Although all unit symbols in that package are suffixed with ᵃ, the suffix should not be used when using this macro.

Note that what goes inside must be parsable as a valid Julia expression.

Examples

julia> using DimensionfulAngles
+2.1
source
DimensionfulAngles.@ua_str — Macro
macro ua_str(unit)

String macro to easily recall units with angular dimension located in the DimensionfulAngles package. Although all unit symbols in that package are suffixed with ᵃ, the suffix should not be used when using this macro.

Note that what goes inside must be parsable as a valid Julia expression.

Examples

julia> using DimensionfulAngles
 
 julia> 1.0ua"turn"
 1.0 τ
 
 julia> 1.0ua"rad" - 1.0ua"°"
-0.9825467074800567 rad
source
DimensionfulAngles.DefaultSymbols — Module

Imports default units into the workspace.

This replicates the behavior of Unitful.DefaultSymbols in Unitful.jl/src/pkgdefaults.jl but replaces Unitful Angles with DimensionfulAngles angles.

Examples

julia> using DimensionfulAngles.DefaultSymbols

will bring the following into the calling namespace:

  • Dimensions 𝐋,𝐌,𝐓,𝐈,𝚯,𝐉,𝐍 and 𝐀

  • Base and derived SI units, with SI prefixes

    • Candela conflicts with Base.cd so it is brought in as cdᵤ.

  • Degrees: °

All angles and derived units imported removing the ᵃ superscript.

Potential conflict with other packages

All angles are imported removing the ᵃ superscript. This means, e.g., ° == u"°ᵃ" instead of u"°". This may cause conflicts with other packages that assume angles are the dimensionless ones from Unitful.

source

Syntax provided by Unitful.jl

DimensionfulAngles.Angle — Type
DimensionfulAngles.Angle{T, U}

A supertype for quantities and levels of dimension DimensionfulAngles.𝐀 with a value of type T and units U.

See also: DimensionfulAngles.𝐀, Unitful.Quantity, Unitful.Level.

source
DimensionfulAngles.AngleUnits — Type
DimensionfulAngles.AngleUnits{U}

A supertype for units of dimension DimensionfulAngles.𝐀. Equivalent to Unitful.Units{U, DimensionfulAngles.𝐀}.

See also: DimensionfulAngles.𝐀, Unitful.Units.

source
DimensionfulAngles.AngleFreeUnits — Type
DimensionfulAngles.AngleFreeUnits{U}

A supertype for Unitful.FreeUnits of dimension DimensionfulAngles.𝐀. Equivalent to Unitful.FreeUnits{U, DimensionfulAngles.𝐀}.

See also: DimensionfulAngles.𝐀.

source

Prefixed units

DimensionfulAngles.Eradᵃ — Constant
DimensionfulAngles.Eradᵃ

A prefixed unit, equal to 10^18 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.Gradᵃ — Constant
DimensionfulAngles.Gradᵃ

A prefixed unit, equal to 10^9 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.Mradᵃ — Constant
DimensionfulAngles.Mradᵃ

A prefixed unit, equal to 10^6 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.Pradᵃ — Constant
DimensionfulAngles.Pradᵃ

A prefixed unit, equal to 10^15 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.Tradᵃ — Constant
DimensionfulAngles.Tradᵃ

A prefixed unit, equal to 10^12 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.Yradᵃ — Constant
DimensionfulAngles.Yradᵃ

A prefixed unit, equal to 10^24 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.Zradᵃ — Constant
DimensionfulAngles.Zradᵃ

A prefixed unit, equal to 10^21 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.aradᵃ — Constant
DimensionfulAngles.aradᵃ

A prefixed unit, equal to 10^-18 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.cradᵃ — Constant
DimensionfulAngles.cradᵃ

A prefixed unit, equal to 10^-2 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.daradᵃ — Constant
DimensionfulAngles.daradᵃ

A prefixed unit, equal to 10^1 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.dradᵃ — Constant
DimensionfulAngles.dradᵃ

A prefixed unit, equal to 10^-1 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.fradᵃ — Constant
DimensionfulAngles.fradᵃ

A prefixed unit, equal to 10^-15 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.hradᵃ — Constant
DimensionfulAngles.hradᵃ

A prefixed unit, equal to 10^2 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.kradᵃ — Constant
DimensionfulAngles.kradᵃ

A prefixed unit, equal to 10^3 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.mradᵃ — Constant
DimensionfulAngles.mradᵃ

A prefixed unit, equal to 10^-3 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.nradᵃ — Constant
DimensionfulAngles.nradᵃ

A prefixed unit, equal to 10^-9 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.pradᵃ — Constant
DimensionfulAngles.pradᵃ

A prefixed unit, equal to 10^-12 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.yradᵃ — Constant
DimensionfulAngles.yradᵃ

A prefixed unit, equal to 10^-24 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.zradᵃ — Constant
DimensionfulAngles.zradᵃ

A prefixed unit, equal to 10^-21 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.μradᵃ — Constant
DimensionfulAngles.μradᵃ

A prefixed unit, equal to 10^-6 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
+0.9825467074800567 radsource
DimensionfulAngles.DefaultSymbols — Module

Imports default units into the workspace.

This replicates the behavior of Unitful.DefaultSymbols in Unitful.jl/src/pkgdefaults.jl but replaces Unitful Angles with DimensionfulAngles angles.

Examples

julia> using DimensionfulAngles.DefaultSymbols

will bring the following into the calling namespace:

  • Dimensions 𝐋,𝐌,𝐓,𝐈,𝚯,𝐉,𝐍 and 𝐀

  • Base and derived SI units, with SI prefixes

    • Candela conflicts with Base.cd so it is brought in as cdᵤ.

  • Degrees: °

All angles and derived units imported removing the ᵃ superscript.

Potential conflict with other packages

All angles are imported removing the ᵃ superscript. This means, e.g., ° == u"°ᵃ" instead of u"°". This may cause conflicts with other packages that assume angles are the dimensionless ones from Unitful.

source

Syntax provided by Unitful.jl

DimensionfulAngles.Angle — Type
DimensionfulAngles.Angle{T, U}

A supertype for quantities and levels of dimension DimensionfulAngles.𝐀 with a value of type T and units U.

See also: DimensionfulAngles.𝐀, Unitful.Quantity, Unitful.Level.

source
DimensionfulAngles.AngleUnits — Type
DimensionfulAngles.AngleUnits{U}

A supertype for units of dimension DimensionfulAngles.𝐀. Equivalent to Unitful.Units{U, DimensionfulAngles.𝐀}.

See also: DimensionfulAngles.𝐀, Unitful.Units.

source
DimensionfulAngles.AngleFreeUnits — Type
DimensionfulAngles.AngleFreeUnits{U}

A supertype for Unitful.FreeUnits of dimension DimensionfulAngles.𝐀. Equivalent to Unitful.FreeUnits{U, DimensionfulAngles.𝐀}.

See also: DimensionfulAngles.𝐀.

source

Prefixed units

DimensionfulAngles.Eradᵃ — Constant
DimensionfulAngles.Eradᵃ

A prefixed unit, equal to 10^18 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.Gradᵃ — Constant
DimensionfulAngles.Gradᵃ

A prefixed unit, equal to 10^9 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.Mradᵃ — Constant
DimensionfulAngles.Mradᵃ

A prefixed unit, equal to 10^6 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.Pradᵃ — Constant
DimensionfulAngles.Pradᵃ

A prefixed unit, equal to 10^15 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.Tradᵃ — Constant
DimensionfulAngles.Tradᵃ

A prefixed unit, equal to 10^12 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.Yradᵃ — Constant
DimensionfulAngles.Yradᵃ

A prefixed unit, equal to 10^24 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.Zradᵃ — Constant
DimensionfulAngles.Zradᵃ

A prefixed unit, equal to 10^21 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.aradᵃ — Constant
DimensionfulAngles.aradᵃ

A prefixed unit, equal to 10^-18 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.cradᵃ — Constant
DimensionfulAngles.cradᵃ

A prefixed unit, equal to 10^-2 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.daradᵃ — Constant
DimensionfulAngles.daradᵃ

A prefixed unit, equal to 10^1 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.dradᵃ — Constant
DimensionfulAngles.dradᵃ

A prefixed unit, equal to 10^-1 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.fradᵃ — Constant
DimensionfulAngles.fradᵃ

A prefixed unit, equal to 10^-15 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.hradᵃ — Constant
DimensionfulAngles.hradᵃ

A prefixed unit, equal to 10^2 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.kradᵃ — Constant
DimensionfulAngles.kradᵃ

A prefixed unit, equal to 10^3 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.mradᵃ — Constant
DimensionfulAngles.mradᵃ

A prefixed unit, equal to 10^-3 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.nradᵃ — Constant
DimensionfulAngles.nradᵃ

A prefixed unit, equal to 10^-9 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.pradᵃ — Constant
DimensionfulAngles.pradᵃ

A prefixed unit, equal to 10^-12 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.yradᵃ — Constant
DimensionfulAngles.yradᵃ

A prefixed unit, equal to 10^-24 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.zradᵃ — Constant
DimensionfulAngles.zradᵃ

A prefixed unit, equal to 10^-21 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
DimensionfulAngles.μradᵃ — Constant
DimensionfulAngles.μradᵃ

A prefixed unit, equal to 10^-6 radᵃ.

Dimension: 𝐀

See also: DimensionfulAngles.radᵃ.

source
diff --git a/dev/guide/units/index.html b/dev/guide/units/index.html index e36f9c2..39e49e0 100644 --- a/dev/guide/units/index.html +++ b/dev/guide/units/index.html @@ -1,14 +1,14 @@ -Other units of angle · DimensionfulAngles
GitHub

Other units of angle

While the radian (DimensionfulAngles.radᵃ) and the degree (DimensionfulAngles.°ᵃ) should cover must use cases, there are many other units of angle. Based on this table and UnitfulAngles.jl, the following units are also provided:

The documentation for these are found in Syntax.

Astronomical units

In astronomy it is common to measure angles in prefixed arcseconds with the symbol for arcsecond as, i.e., milliarcsecond is mas. DimensionfulAngles.jl provides this alternate, prefixable, version of the arcsecond.

DimensionfulAngles.asᵃ — Constant
asₐ

The arcsecond, a unit of angle defined as 1°/3600.

This is an alternative symbol for DimensionfulAngles.arcsecondᵃ common in astronomy. Unlike arcsecondᵃ, asᵃ accepts SI prefixes. UnitfulAngles has similar implementation for μas, mas, and pas; this differs in that it contains units of angle.

Avoid abbreviation conflicts with `Unitful.jl`

To avoid abbreviation conflicts between attoseconds (as) and arcseconds, and decaseconds (das) and deciarcseconds, the astronomical arcsecond is abbreviated as asₐ instead.

Dimension: 𝐀.

See also DimensionfulAngles.arcsecondᵃ.

source

The prefixed units are documented in Prefixed units.

Another set of units of angle used in astronomy is the hour, minutes, and seconds. Note that these are minutes and seconds of hour, not degree (e.g., like the arcsecond). The hour is defined as $1/24$ of a full revolution. These are usually displayed as, e.g. 10ʰ 5ᵐ 13.2ˢ (see Display).

Note

minutes/seconds of a degree are distinct from minutes/seconds of an hour.

Display

Most of the time we want to express an angle in a single unit. However, in some fields it is common to express them in a sexagesimal system. Dimensionful.jl provides the function show_sexagesimal to display an angle in two different sexagesimal systems. The function sexagesimal returns these values rather than displaying them.

DimensionfulAngles.sexagesimal — Function
sexagesimal(x::Angle; base_unit::AngleUnits=°ᵃ)

Convert an angle to the triple (unit, minutes of unit, seconds of unit), where unit is either degree (°ᵃ) or hour angle (ʰᵃ).

Note

Minutes and seconds of a degree are different from minutes and seconds of an hour angle. In both cases a minute is 1/60ᵗʰ of the base unit and a second is 1/60ᵗʰ of that.

Example

julia> using DimensionfulAngles
+Other units of angle · DimensionfulAngles
GitHub
Other units of angle
While the radian (DimensionfulAngles.radᵃ) and the degree (DimensionfulAngles.°ᵃ) should cover must use cases, there are many other units of angle. Based on this table and UnitfulAngles.jl, the following units are also provided:
The documentation for these are found in Syntax.
Astronomical units
In astronomy it is common to measure angles in prefixed arcseconds with the symbol for arcsecond as, i.e., milliarcsecond is mas. DimensionfulAngles.jl provides this alternate, prefixable, version of the arcsecond.
DimensionfulAngles.asᵃ — Constant
asₐ
The arcsecond, a unit of angle defined as 1°/3600.
This is an alternative symbol for DimensionfulAngles.arcsecondᵃ common in astronomy. Unlike arcsecondᵃ, asᵃ accepts SI prefixes. UnitfulAngles has similar implementation for μas, mas, and pas; this differs in that it contains units of angle.
Avoid abbreviation conflicts with `Unitful.jl`
To avoid abbreviation conflicts between attoseconds (as) and arcseconds, and decaseconds (das) and deciarcseconds, the astronomical arcsecond is abbreviated as asₐ instead.
Dimension: 𝐀.
See also DimensionfulAngles.arcsecondᵃ.
source
The prefixed units are documented in Prefixed units.
Another set of units of angle used in astronomy is the hour, minutes, and seconds. Note that these are minutes and seconds of hour, not degree (e.g., like the arcsecond). The hour is defined as $1/24$ of a full revolution. These are usually displayed as, e.g. 10ʰ 5ᵐ 13.2ˢ (see Display).
Note
minutes/seconds of a degree are distinct from minutes/seconds of an hour.
Display
Most of the time we want to express an angle in a single unit. However, in some fields it is common to express them in a sexagesimal system. Dimensionful.jl provides the function show_sexagesimal to display an angle in two different sexagesimal systems. The function sexagesimal returns these values rather than displaying them.
DimensionfulAngles.sexagesimal — Function
sexagesimal(x::Angle; base_unit::AngleUnits=°ᵃ)
Convert an angle to the triple (unit, minutes of unit, seconds of unit), where unit is either degree (°ᵃ) or hour angle (ʰᵃ).
Note
Minutes and seconds of a degree are different from minutes and seconds of an hour angle. In both cases a minute is 1/60ᵗʰ of the base unit and a second is 1/60ᵗʰ of that.
Example
julia> using DimensionfulAngles
 
 julia> sexagesimal(20.2ua"°")
 (20°, 11′, 59.99999999999746″)
 
 julia> sexagesimal(20.2ua"°"; base_unit = ua"ʰ")
-(1ʰ, 20ᵐ, 48.000000000000256ˢ)
source
DimensionfulAngles.show_sexagesimal — Function
show_sexagesimal(x::Angle; base_unit::AngleUnits=°ᵃ)
Print an angle in units (u), minutes of unit (m), and seconds of unit (s) where unit is either degree (°ᵃ) or hour angle (ʰ). For degrees it is printed as u° m′ s″ and for hour angle as uʰ mᵐ sˢ.
Example
julia> using DimensionfulAngles
+(1ʰ, 20ᵐ, 48.000000000000256ˢ)
source
DimensionfulAngles.show_sexagesimal — Function
show_sexagesimal(x::Angle; base_unit::AngleUnits=°ᵃ)
Print an angle in units (u), minutes of unit (m), and seconds of unit (s) where unit is either degree (°ᵃ) or hour angle (ʰ). For degrees it is printed as u° m′ s″ and for hour angle as uʰ mᵐ sˢ.
Example
julia> using DimensionfulAngles
 
 julia> show_sexagesimal(20.2ua"°")
 20° 11′ 59.99999999999746″
 
 julia> show_sexagesimal(20.2ua"°"; base_unit = ua"ʰ")
-1ʰ 20ᵐ 48.000000000000256ˢ
source
For most units, a space is inserted between the value and the unit, which is the default behavior from Unitful.jl. For the following units, this space is removed (e.g., 10° not 10 °):
  • °
  • ′
  • ″
  • ʰ
  • ᵐ
  • ˢ
Syntax
Contents:
DimensionfulAngles.turnᵃ — Constant
turnᵃ
The turn, a unit of angle defined as 2π rad.
Equivalent to a full cycle, revolution, or rotation. This differs from UnitfulAngles.turn in that it contains units of angle. Does not accepts SI prefixes.
Dimension: 𝐀.
See also DimensionfulAngles.radᵃ.
source
DimensionfulAngles.bradᵃ — Constant
bradᵃ
The binary radian, a unit of angle defined as 1/256 turn.
Also known as the binary degree. This differs from UnitfulAngles.brad in that it contains units of angle. Does not accepts SI prefixes.
Dimension: 𝐀.
See also DimensionfulAngles.turnᵃ.
source
Prefixed units

+1ʰ 20ᵐ 48.000000000000256ˢ
source

For most units, a space is inserted between the value and the unit, which is the default behavior from Unitful.jl. For the following units, this space is removed (e.g., 10° not 10 °):

  • °
  • ′
  • ″
  • ʰ
  • ᵐ
  • ˢ

Syntax

Contents:

DimensionfulAngles.turnᵃ — Constant
turnᵃ

The turn, a unit of angle defined as 2π rad.

Equivalent to a full cycle, revolution, or rotation. This differs from UnitfulAngles.turn in that it contains units of angle. Does not accepts SI prefixes.

Dimension: 𝐀.

See also DimensionfulAngles.radᵃ.

source
DimensionfulAngles.bradᵃ — Constant
bradᵃ

The binary radian, a unit of angle defined as 1/256 turn.

Also known as the binary degree. This differs from UnitfulAngles.brad in that it contains units of angle. Does not accepts SI prefixes.

Dimension: 𝐀.

See also DimensionfulAngles.turnᵃ.

source

Prefixed units

diff --git a/dev/index.html b/dev/index.html index 021c70f..20163ea 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · DimensionfulAngles
GitHub

DimensionfulAngles.jl

An extension of Unitful.jl to include angle as a dimension.

While angle is not an SI base dimension, it can be extremely useful to consider it as one in computer units systems. This allows, among other things, dispatching on angles. This package creates a single additional dimension angle which is assigned to both plane and phase angles.

Note

Please read through the Unitful.jl documentation first. This package extends Unitful.jl and documentation for the main usage and features of Unitful.jl are not duplicated here.

Angle as a dimension?

For motivating examples on why this is useful, see Angle as a dimension?. The main takeaway is that

While the choice to use the SI dimensions in Unitful is the right one, for use cases that deal extensively with a dimensionless quantity, it can be extremely useful to extend the base dimensions to include that quantity. This package extends it to use angles as a dimension.

Package Guide

The Package Guide is the main documentation for the package and includes usage details and examples of all of DimensionfulAngles.jl's capabilities. These include

  • Angle as a base dimension.
  • A comprehensive list of angular units.
  • The @ua_str macro for easily accessing these units.
  • Derived dimensions and their units, including: solid angles, angular velocity/frequency, angular acceleration, luminous flux, illuminance, etc.
  • Conversion between Unitful and DimensionfulAngles quantities.
  • A UnitfulEquivalences.jl Equivalence to convert between period, frequency, and angular frequency of a periodic response.
  • A comprehensive extension of functions in Base that take angular quantities as inputs, or output angular quantities.

Relationship to proposed SI extensions

This package extends the number of base dimensions solely for convenience when working with unitful quantities on a computer. This package does not propose or promote any official extension of the SI system. Such proposals do exist, and for completeness these are discussed in Relation to proposed SI extensions.

Definitions

These definitions are based on the SI Brochure. In particular note the distinction between a quantity (which has a value and a unit), its unit, and its dimension. Any physical quantity hasa unique standard (coherent) SI unit and dimension, but the converse is not true. E.g. both torque and energy, two distinct quantities, have the same dimension and units. Also note the distinction between plane and phase angles as distinct quantities, and angular velocity and angular frequency as distinct quantities.

  • Angle: Either a plane or phase angle.
  • Plane Angle: The angle between two lines originating from a common point.
  • Phase Angle or Phase: The argument of a complex number, i.e. the angle between the real axis and the radius of the polar representation of the complex number in the complex plane.
  • Unit: A particular example of the quantity concerned which is used as a reference. For a particular quantity different units may be used.
  • Dimension: A conventional system for organizing physical quantities. In the SI the seven base quantities are each assigned one dimension. The dimensions of all other (derived) quantities are written as a product of powers of the base dimensions according to the equations of physics that relate these quantities.
+Home · DimensionfulAngles
GitHub

DimensionfulAngles.jl

An extension of Unitful.jl to include angle as a dimension.

While angle is not an SI base dimension, it can be extremely useful to consider it as one in computer units systems. This allows, among other things, dispatching on angles. This package creates a single additional dimension angle which is assigned to both plane and phase angles.

Note

Please read through the Unitful.jl documentation first. This package extends Unitful.jl and documentation for the main usage and features of Unitful.jl are not duplicated here.

Angle as a dimension?

For motivating examples on why this is useful, see Angle as a dimension?. The main takeaway is that

While the choice to use the SI dimensions in Unitful is the right one, for use cases that deal extensively with a dimensionless quantity, it can be extremely useful to extend the base dimensions to include that quantity. This package extends it to use angles as a dimension.

Package Guide

The Package Guide is the main documentation for the package and includes usage details and examples of all of DimensionfulAngles.jl's capabilities. These include

  • Angle as a base dimension.
  • A comprehensive list of angular units.
  • The @ua_str macro for easily accessing these units.
  • Derived dimensions and their units, including: solid angles, angular velocity/frequency, angular acceleration, luminous flux, illuminance, etc.
  • Conversion between Unitful and DimensionfulAngles quantities.
  • A UnitfulEquivalences.jl Equivalence to convert between period, frequency, and angular frequency of a periodic response.
  • A comprehensive extension of functions in Base that take angular quantities as inputs, or output angular quantities.

Relationship to proposed SI extensions

This package extends the number of base dimensions solely for convenience when working with unitful quantities on a computer. This package does not propose or promote any official extension of the SI system. Such proposals do exist, and for completeness these are discussed in Relation to proposed SI extensions.

Definitions

These definitions are based on the SI Brochure. In particular note the distinction between a quantity (which has a value and a unit), its unit, and its dimension. Any physical quantity hasa unique standard (coherent) SI unit and dimension, but the converse is not true. E.g. both torque and energy, two distinct quantities, have the same dimension and units. Also note the distinction between plane and phase angles as distinct quantities, and angular velocity and angular frequency as distinct quantities.

  • Angle: Either a plane or phase angle.
  • Plane Angle: The angle between two lines originating from a common point.
  • Phase Angle or Phase: The argument of a complex number, i.e. the angle between the real axis and the radius of the polar representation of the complex number in the complex plane.
  • Unit: A particular example of the quantity concerned which is used as a reference. For a particular quantity different units may be used.
  • Dimension: A conventional system for organizing physical quantities. In the SI the seven base quantities are each assigned one dimension. The dimensions of all other (derived) quantities are written as a product of powers of the base dimensions according to the equations of physics that relate these quantities.
diff --git a/dev/motivation/index.html b/dev/motivation/index.html index 4f56755..17b3253 100644 --- a/dev/motivation/index.html +++ b/dev/motivation/index.html @@ -51,4 +51,4 @@ "I am an angle?" julia> what_am_i(percent) -"I am an angle?"

Takeaways

The main takeaway is that

While the choice to use the SI dimensions in Unitful is the right one, for use cases that deal extensively with a dimensionless quantity, it can be extremely useful to extend the base dimensions to include that quantity. This package extends it to use angles as a dimension.

There will always be quantities which are dimensionless and have units of 1 as well as distinct quantities with the same dimensions. There is no "complete" system and this package is simply an extension to facilitate working with angles specifically. And while this resolves some confusion between, for example frequency and angular frequency (which have the same dimension in SI), there are still different quantities with the same dimension of angle, namely plane angles and phase angles.

+"I am an angle?"

Takeaways

The main takeaway is that

While the choice to use the SI dimensions in Unitful is the right one, for use cases that deal extensively with a dimensionless quantity, it can be extremely useful to extend the base dimensions to include that quantity. This package extends it to use angles as a dimension.

There will always be quantities which are dimensionless and have units of 1 as well as distinct quantities with the same dimensions. There is no "complete" system and this package is simply an extension to facilitate working with angles specifically. And while this resolves some confusion between, for example frequency and angular frequency (which have the same dimension in SI), there are still different quantities with the same dimension of angle, namely plane angles and phase angles.

diff --git a/dev/objects.inv b/dev/objects.inv new file mode 100644 index 0000000..5834d24 Binary files /dev/null and b/dev/objects.inv differ diff --git a/dev/proposed/index.html b/dev/proposed/index.html index 83882f1..3858f4d 100644 --- a/dev/proposed/index.html +++ b/dev/proposed/index.html @@ -1,3 +1,3 @@ Relationship to proposed SI extensions. · DimensionfulAngles
GitHub

Relation to proposed SI extensions

The concept of dimensions has some limitations (see [1], [2], and [3], which have led to many proposed extensions to the SI system, including many proposals to include angles as a dimension. Several such proposals include [4], [5], [6], and references therein.

Summary of proposals

The exact form of the proposals and their effects on the equations of physics are all different, but most (i) include angle as a base dimension, (ii) use a "fundamental" constant, typically equal to one radian, to modify the equations of physics, and (iii) define solid angle as a derived dimension equal to angle squared. The different proposals, however, take different approaches to which equations or quantity units to modify. One exception not considered here is a class of proposals that define a new dimension for radius length rather than for angle.

Some examples of how common equations would be modified in such systems, using $θ₀=1rad$:

  • Trigonometric & exponential functions:

    • $cos(θ) → cos(θ/θ₀)$
    • $cos(ωt+φ) → cos([ωt+φ]/θ₀)$
    • $Aℯⁱᶿ → Aℯ^[iθ/θ₀]$

  • Angular frequency and angular wave number:

    • $ω=2πf → ω=2πfθ₀$
    • $k=2π/λ → k=2πθ₀/λ$

  • Arc length and sector area:

    • $s=rθ → s=rθ/θ₀$
    • $A=½r²θ → A=½r²θ/θ₀$

  • Solid angles

    • $Ω=A/r² → Ω=Aθ₀²/r²$

  • kinematic equations:

    • $v=rω → v=rω/θ₀$
    • $a=rω² → a=rω²/θ₀²$

  • For dynamic equations, there's more variability between the different proposals. As an example, [5] would modify the units of torque and moment of inertia while leaving the units of work and energy intact.

    • $T=(𝐫×𝐅) → T=(𝐫×𝐅)/θ₀$ (torque, new units: $J/s$)
    • $I=Σ(mᵢ⋅rᵢ)/θ₀²$ (moment of inertia, new units: $kg⋅m²/rad²$)
    • $L=Iω=(𝐫×𝐩)/θ₀$ (angular momentum, new units: $J/(rad/s)$)
    • $W=Tθ$ (work)
    • $E=½Iω²$ (kinetic energy)

DimensionfulAngles.jl's relation to these proposals

DimensionfulAngles.jl extends the number of base dimensions solely for convenience when working with unitful quantities on a computer. It does not propose or promote any official extension of the SI system such as those summarized above. However, there's a few ideas we borrow from these proposals, namely:

1. Defining constant

The constant θ₀=1rad is provided as a hypothetical "defining unit" or "fundamental constant", mostly for analogy/consistency with the other base dimensions in the SI and Unitful.jl.

2. Solid angles

Solid angles are considered a derived dimension equal to angle squared (𝐀²). This is in agreement with the proposals discussed above.

Normalizing with θ₀

In contrast to these proposals, one of the goals of this package is to not require the use of the constant θ₀ for normalizing inputs to common functions. To this end, the extensions to functions in Base ensure that function calls like

julia> cos(45ua"°")
-0.7071067811865476

work without having to use the constant θ₀ to normalize the argument. Please report any function in Base or in the standard library that should handle arguments of a dimension that includes angles but is not currently covered by this package. A goal of this package is to cover all such functions as well as those whose output should be of dimensions that includes angles.

While we try to cover most sensical functions, you will most likely have to manually remove angle units (e.g. normalizing with θ₀ as above) when dealing with dynamic equations (e.g. the torque relationship above). To this end it might be beneficial to be consistent and follow a specific system/proposal.

Functions in other packages for which it would make sense to provide arguments with dimensions including angles will not immediately work. You will likely need to convert to radians and then strip the units before providing the quantity as an argument to that function. This can be done in several ways, including through the use of the constant θ₀ for normalization. Alternatively, you can expand those functions to accept dimensionful angles by defining new methods. If you believe such expansion should be included in DimensionfulAngles.jl (e.g. to cover a very popular package) please create an issue in the GitHub repository.

References

[1]
BIPM. Le Système international d'unités / The International System of Units (‘The SI Brochure’). Ninth Edition (Bureau international des poids et mesures, 2019).
[2]
[3]
[4]
[5]
[6]
+0.7071067811865476

work without having to use the constant θ₀ to normalize the argument. Please report any function in Base or in the standard library that should handle arguments of a dimension that includes angles but is not currently covered by this package. A goal of this package is to cover all such functions as well as those whose output should be of dimensions that includes angles.

While we try to cover most sensical functions, you will most likely have to manually remove angle units (e.g. normalizing with θ₀ as above) when dealing with dynamic equations (e.g. the torque relationship above). To this end it might be beneficial to be consistent and follow a specific system/proposal.

Functions in other packages for which it would make sense to provide arguments with dimensions including angles will not immediately work. You will likely need to convert to radians and then strip the units before providing the quantity as an argument to that function. This can be done in several ways, including through the use of the constant θ₀ for normalization. Alternatively, you can expand those functions to accept dimensionful angles by defining new methods. If you believe such expansion should be included in DimensionfulAngles.jl (e.g. to cover a very popular package) please create an issue in the GitHub repository.

References

[1]
BIPM. Le Système international d'unités / The International System of Units (‘The SI Brochure’). Ninth Edition (Bureau international des poids et mesures, 2019).
[2]
[3]
[4]
[5]
[6]
diff --git a/dev/syntax/index.html b/dev/syntax/index.html index b26dd1f..3b5551b 100644 --- a/dev/syntax/index.html +++ b/dev/syntax/index.html @@ -1,2 +1,2 @@ -Index · DimensionfulAngles
GitHub

Index

+Index · DimensionfulAngles
GitHub

Index