From 1c75a5040301383ad6d9dcb163af5eec1f090d7b Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Sun, 21 Jul 2024 05:48:47 +0000 Subject: [PATCH] build based on 6dc4dbf --- dev/.documenter-siteinfo.json | 2 +- dev/assets/documenter.js | 932 ++++++++++++--------- dev/assets/themes/catppuccin-frappe.css | 1 + dev/assets/themes/catppuccin-latte.css | 1 + dev/assets/themes/catppuccin-macchiato.css | 1 + dev/assets/themes/catppuccin-mocha.css | 1 + dev/assets/themes/documenter-dark.css | 4 +- dev/assets/themes/documenter-light.css | 2 +- dev/design/index.html | 4 +- dev/docstrings/index.html | 108 +-- dev/index.html | 22 +- dev/objects.inv | Bin 0 -> 3008 bytes dev/theory/automorphisms/index.html | 2 +- dev/theory/basics/index.html | 27 +- dev/theory/dualities/index.html | 4 +- dev/theory/products/index.html | 4 +- dev/theory/references/index.html | 2 +- dev/theory/rotors/index.html | 2 +- dev/theory/special/index.html | 4 +- 19 files changed, 648 insertions(+), 475 deletions(-) create mode 100644 dev/assets/themes/catppuccin-frappe.css create mode 100644 dev/assets/themes/catppuccin-latte.css create mode 100644 dev/assets/themes/catppuccin-macchiato.css create mode 100644 dev/assets/themes/catppuccin-mocha.css create mode 100644 dev/objects.inv diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 82e5e31..9755809 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.8.5","generation_timestamp":"2024-01-04T02:43:31","documenter_version":"1.2.1"}} \ No newline at end of file +{"documenter":{"julia_version":"1.8.5","generation_timestamp":"2024-07-21T05:48:45","documenter_version":"1.5.0"}} \ No newline at end of file diff --git a/dev/assets/documenter.js b/dev/assets/documenter.js index 4930f82..0a26a09 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', @@ -108,9 +107,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) { @@ -121,7 +121,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") @@ -132,7 +132,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); @@ -229,224 +229,474 @@ $(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); + + /** + * 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 || ""; + } + + /** + * RegX escape function from MDN + * Refer: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping + */ + function escapeRegExp(string) { + return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string + } -index.addAll(data); + /** + * 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})`; + } + searchstring = escapeRegExp(querystring); + let textindex = new RegExp(`${searchstring}`, "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(searchstring)}`, "i"), // For first occurrence + '$&' + ) + + "..." + : ""; // highlights the match + + let in_code = false; + if (!["page", "section"].includes(result.category.toLowerCase())) { + in_code = true; + } -let filters = [...new Set(data.map((x) => x.category))]; -var modal_filters = make_modal_body_filters(filters); -var filter_results = []; + // 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; + } -$(document).on("keyup", ".documenter-search-input", function (event) { - // Adding a debounce to prevent disruptions from super-speed typing! - debounce(() => update_search(filter_results), 300); + self.onmessage = function (e) { + let query = e.data; + let results = index.search(query, { + filter: (result) => { + // Only return relevant results + return result.score >= 1; + }, + combineWith: "AND", + }); + + // 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) { @@ -454,19 +704,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 = `
@@ -495,125 +749,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); +
`; } }) @@ -640,103 +806,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( - ` - diff --git a/dev/theory/dualities/index.html b/dev/theory/dualities/index.html index dc5d4cb..7fa596b 100644 --- a/dev/theory/dualities/index.html +++ b/dev/theory/dualities/index.html @@ -1,3 +1,3 @@ -Dualities · GeometricAlgebra.jl
GitHub

Dualities

Pseudoscalar duality

The highest-grade elements of geometric algebras are called pseudoscalars. The unit pseudoscalar

\[I ≔ 𝐯_1𝐯_2⋯𝐯_n\]

plays an important role, and may be interpreted as an oriented unit volume.

Warning

The unit pseudoscalar $I$ is not to be confused with the identity matrix or unit imaginary $i$. Indeed, $I$ does not always commute, and $I^2 = ±1$ depending on the algebra.

Multiplying by $I$ sends $k$-vectors to $(n - k)$-vectors. In odd dimensions, left- and right-multiplication by the unit pseudoscalar is identical:

\[AI = IA -\quad\text{(in odd dimensions)}\]

for any multivector $A$. However, in even dimensions, odd-grade elements anticommute with $I$.

Hodge duality

hodgedual(A)

The Hodge dual is a combination of reversion and multiplication by $I$:

\[\mathsf{hodgedual}(A) = \tilde{A}I\]

This comes from the Hodge star operator from exterior algebra, which is a metrical duality operation implicitly defined on two $k$-vectors $A$ and $B$ by

\[A ∧ \mathsf{hodgedual}(B) = ⟨A, B⟩ I\]

where $⟨A, B⟩$ is the induced inner product on $k$-vectors. In the language of geometric algebra, this is

\[⟨A, B⟩ = A \odot \tilde{B} = A \lcontr \tilde{B}\]

and by using the identity $(A \lcontr \tilde{B})I = A ∧ (\tilde{B}I)$ we have $A ∧ \mathsf{hodgedual}(B) = A ∧ (\tilde{B}I)$ which shows the equivalence with the explicit definition above.

Comparison with pseudoscalar-duality

For homogeneous multivectors, Hodge duality and pseudoscalar-duality differ only in overall sign.

The square of the Hodge dual is $\mathsf{hodgedual}^2(A) = (-1)^s(-1)^{k(n - k)} A$ and hence the inverse is

\[\mathsf{hodgedual}^{-1}(A) = (-1)^s(-1)^{k(n - k)} \mathsf{hodgedual}(A) \]

where $s$ is the trace of the metric.[1] Note that this depends on the grade $k$ of $A$.

By contrast, $I^2 = ±1$ and hence $I^{-1} = ±I$ does not depend on the multivector it acts on. (This generally makes pseudoscalar-duality easier to work with algebraically!)

Left and right complements

ldual, rdual

The left and right complements are dual operations which do not involve multiplication by the pseudoscalar $I$, and so are metric independent. Some authors denote the left and right complements by $\underline{A}$ and $\overline{A}$, respectively.

For a unit basis blade $a$, the complements are uniquely defined by

\[\textsf{ldual}(a)\,a = I = a\,\textsf{rdual}(a)\]

and are extended linearly to act on general multivectors. They are inverses of each other,

\[\textsf{ldual}(\textsf{rdual}(a)) = a = \textsf{rdual}(\textsf{ldual}(a))\]

and in odd-dimensional algebras, are identical.

The metric-independence of the left and right duals mean they are useful even in degenerate algebras, since a non-zero multivector always has a non-zero dual even when its Hodge dual is zero.

Dualized products

It is common to work both with multivectors and their duals in the same context, and hence convenient to define “dualized” versions of certain products. For example, the regressive product $∨$ is the dualized wedge product $∧$, defined by

\[D(a ∨ b) = D(a) ∧ D(b)\]

where $D$ is a dual operation such as $\textsf{ldual}$ or $\textsf{rdual}$ (each results in an equivalent definition).

In the context of point-based projective geometric algebra, the $∧$-product of two objects forms the join (e.g., the line joining two points) while the $∨$-product of two objects forms the meet (e.g., the point where two lines meet) and vice versa in plane-based PGA.

Similar products may be defined by dualizing the inner product and contractions[2] but these are less common.

+Dualities · GeometricAlgebra.jl
GitHub

Dualities

Pseudoscalar duality

The highest-grade elements of geometric algebras are called pseudoscalars. The unit pseudoscalar

\[I ≔ 𝐯_1𝐯_2⋯𝐯_n\]

plays an important role, and may be interpreted as an oriented unit volume.

Warning

The unit pseudoscalar $I$ is not to be confused with the identity matrix or unit imaginary $i$. Indeed, $I$ does not always commute, and $I^2 = ±1$ depending on the algebra.

Multiplying by $I$ sends $k$-vectors to $(n - k)$-vectors. In odd dimensions, left- and right-multiplication by the unit pseudoscalar is identical:

\[AI = IA +\quad\text{(in odd dimensions)}\]

for any multivector $A$. However, in even dimensions, odd-grade elements anticommute with $I$.

Hodge duality

hodgedual(A)

The Hodge dual is a combination of reversion and multiplication by $I$:

\[\mathsf{hodgedual}(A) = \tilde{A}I\]

This comes from the Hodge star operator from exterior algebra, which is a metrical duality operation implicitly defined on two $k$-vectors $A$ and $B$ by

\[A ∧ \mathsf{hodgedual}(B) = ⟨A, B⟩ I\]

where $⟨A, B⟩$ is the induced inner product on $k$-vectors. In the language of geometric algebra, this is

\[⟨A, B⟩ = A \odot \tilde{B} = A \lcontr \tilde{B}\]

and by using the identity $(A \lcontr \tilde{B})I = A ∧ (\tilde{B}I)$ we have $A ∧ \mathsf{hodgedual}(B) = A ∧ (\tilde{B}I)$ which shows the equivalence with the explicit definition above.

Comparison with pseudoscalar-duality

For homogeneous multivectors, Hodge duality and pseudoscalar-duality differ only in overall sign.

The square of the Hodge dual is $\mathsf{hodgedual}^2(A) = (-1)^s(-1)^{k(n - k)} A$ and hence the inverse is

\[\mathsf{hodgedual}^{-1}(A) = (-1)^s(-1)^{k(n - k)} \mathsf{hodgedual}(A) \]

where $s$ is the trace of the metric.[1] Note that this depends on the grade $k$ of $A$.

By contrast, $I^2 = ±1$ and hence $I^{-1} = ±I$ does not depend on the multivector it acts on. (This generally makes pseudoscalar-duality easier to work with algebraically!)

Left and right complements

ldual, rdual

The left and right complements are dual operations which do not involve multiplication by the pseudoscalar $I$, and so are metric independent. Some authors denote the left and right complements by $\underline{A}$ and $\overline{A}$, respectively.

For a unit basis blade $a$, the complements are uniquely defined by

\[\textsf{ldual}(a)\,a = I = a\,\textsf{rdual}(a)\]

and are extended linearly to act on general multivectors. They are inverses of each other,

\[\textsf{ldual}(\textsf{rdual}(a)) = a = \textsf{rdual}(\textsf{ldual}(a))\]

and in odd-dimensional algebras, are identical.

The metric-independence of the left and right duals mean they are useful even in degenerate algebras, since a non-zero multivector always has a non-zero dual even when its Hodge dual is zero.

Dualized products

It is common to work both with multivectors and their duals in the same context, and hence convenient to define “dualized” versions of certain products. For example, the regressive product $∨$ is the dualized wedge product $∧$, defined by

\[D(a ∨ b) = D(a) ∧ D(b)\]

where $D$ is a dual operation such as $\textsf{ldual}$ or $\textsf{rdual}$ (each results in an equivalent definition).

In the context of point-based projective geometric algebra, the $∧$-product of two objects forms the join (e.g., the line joining two points) while the $∨$-product of two objects forms the meet (e.g., the point where two lines meet) and vice versa in plane-based PGA.

Similar products may be defined by dualizing the inner product and contractions[2] but these are less common.

diff --git a/dev/theory/products/index.html b/dev/theory/products/index.html index 2d6cf29..03aaec9 100644 --- a/dev/theory/products/index.html +++ b/dev/theory/products/index.html @@ -1,5 +1,5 @@ -Wedge, Inner and Other Products · GeometricAlgebra.jl
GitHub

Wedge, Inner and Other Products

The geometric product is the fundamental operation in geometric algebra. Together with grade projection $⟨\phantom{A}⟩_k$, various other “graded products” may be defined by taking different projections of the geometric product.

To motivate this, consider a $p$-vector $A$ and $q$-vector $B$. The geometric product contains parts of every grade between the difference $|p - q|$ and sum $p + q$ in steps of two:

\[AB = ⟨AB⟩_{|p - q|} + ⟨AB⟩_{|p - q| + 2} + ⋯ + ⟨AB⟩_{p + q - 2} + ⟨AB⟩_{p + q}\]

Some of these parts are often useful on their own, and so warrant their own name.

These are summarised below, where the grade of the result is shown for each product between a $p$-vector and $q$-vector.

NameSymbolREPL shortcutResulting grade
scalar$\odot$\odot<tab>$0$
wedge$∧$\wedge<tab>$p + q$
inner$⋅$\cdot<tab>$|p - q|$
left contraction$\lcontr$\intprod<tab>$q - p$
right contraction$\rcontr$\intprodr<tab>$p - q$

To glance at a multiplication table for a product, you can use cayleytable. For example, left contraction in $Cl(1,1)$ looks like:

cayleytable(Cl(1,1), ⨼)
 (↓) ⨼ (→) │ 1 │ v1  v2 │ v12
+Wedge, Inner and Other Products · GeometricAlgebra.jl
GitHub
Wedge, Inner and Other Products
The geometric product is the fundamental operation in geometric algebra. Together with grade projection $⟨\phantom{A}⟩_k$, various other “graded products” may be defined by taking different projections of the geometric product.
To motivate this, consider a $p$-vector $A$ and $q$-vector $B$. The geometric product contains parts of every grade between the difference $|p - q|$ and sum $p + q$ in steps of two:
\[AB = ⟨AB⟩_{|p - q|} + ⟨AB⟩_{|p - q| + 2} + ⋯ + ⟨AB⟩_{p + q - 2} + ⟨AB⟩_{p + q}\]
Some of these parts are often useful on their own, and so warrant their own name.
These are summarised below, where the grade of the result is shown for each product between a $p$-vector and $q$-vector.
NameSymbolREPL shortcutResulting grade
scalar$\odot$\odot<tab>$0$
wedge$∧$\wedge<tab>$p + q$
inner$⋅$\cdot<tab>$|p - q|$
left contraction$\lcontr$\intprod<tab>$q - p$
right contraction$\rcontr$\intprodr<tab>$p - q$
To glance at a multiplication table for a product, you can use cayleytable. For example, left contraction in $Cl(1,1)$ looks like:
cayleytable(Cl(1,1), ⨼)
 (↓) ⨼ (→) │ 1 │ v1  v2 │ v12
 ───────────┼───┼────────┼─────
          1 │ 1 │ v1  v2 │ v12
 ───────────┼───┼────────┼─────
@@ -23,4 +23,4 @@
 ,&	(A \rcontr B) \rcontr C &= A \rcontr (B ∧ C)
 \\	A \odot (B \lcontr C) &= (A ∧ B) \odot C
 ,&	(A \rcontr B) \odot C &= A \odot (B ∧ C)
-\end{align*}\]
where $I$ is the unit pseudoscalar.[1]
Other Products
Commutator product
The commutator product is defined as
\[A × B ≔ \frac12(AB - BA)\]
  • 1Section 3.3, [2]

+\end{align*}\]
where $I$ is the unit pseudoscalar.[1]
Other Products
Commutator product
The commutator product is defined as
\[A × B ≔ \frac12(AB - BA)\]
  • 1Section 3.3, [2]
diff --git a/dev/theory/references/index.html b/dev/theory/references/index.html index c3eb908..9996036 100644 --- a/dev/theory/references/index.html +++ b/dev/theory/references/index.html @@ -1,2 +1,2 @@ -References · GeometricAlgebra.jl
GitHub

References

[1]
L. Dorst. The Inner Products of Geometric Algebra. In: Applications of Geometric Algebra in Computer Science and Engineering, edited by L. Dorst, C. Doran and J. Lasenby (Birkhäuser, Boston, MA, 2002); pp. 35–46.
[2]
J. Wilson. Geometric Algebra for Special Relativity and Manifold Geometry. Master's thesis, Victoria University of Wellington (Sep 2022).
[3]
[4]
D. Prodanov. Algorithmic Computation of Multivector Inverses and Characteristic Polynomials in Non-degenerate Clifford Algebras. In: Advances in Computer Graphics, edited by B. Sheng, L. Bi, J. Kim, N. Magnenat-Thalmann and D. Thalmann (Springer Nature Switzerland, Cham, 2024); pp. 379–390.
+References · GeometricAlgebra.jl
GitHub

References

[1]
L. Dorst. The Inner Products of Geometric Algebra. In: Applications of Geometric Algebra in Computer Science and Engineering, edited by L. Dorst, C. Doran and J. Lasenby (Birkhäuser, Boston, MA, 2002); pp. 35–46.
[2]
J. Wilson. Geometric Algebra for Special Relativity and Manifold Geometry. Master's thesis, Victoria University of Wellington (Sep 2022).
[3]
[4]
D. Prodanov. Algorithmic Computation of Multivector Inverses and Characteristic Polynomials in Non-degenerate Clifford Algebras. In: Advances in Computer Graphics, edited by B. Sheng, L. Bi, J. Kim, N. Magnenat-Thalmann and D. Thalmann (Springer Nature Switzerland, Cham, 2024); pp. 379–390.
diff --git a/dev/theory/rotors/index.html b/dev/theory/rotors/index.html index e71a281..98fdaa6 100644 --- a/dev/theory/rotors/index.html +++ b/dev/theory/rotors/index.html @@ -1,2 +1,2 @@ -Rotors · GeometricAlgebra.jl
GitHub

Rotors

Rotors are multivectors which describe proper rotations. The rotor formalism provides an extremely uniform, elegant and efficient description of rotations. For motivation, it is helpful to consider rotations in simpler algebras.

In the complex plane, a complex number $z ∈ ℂ$ is rotated about the origin with the mapping $z ↦ e^{iθ}z$. Similarly, a quaternion $q ∈ ℍ$ is rotated about an axis $n$ with $q ↦ e^{n/2}qe^{-n/2}$. Indeed, the double-sided transformation law

\[A ↦ e^{B/2}Ae^{-B/2}\]

is general to both $ℂ$ and $ℍ$, and in fact applies to geometric algebras of any dimension. Specifically, the rotor $R = e^{B/2}$ describes a rotation in the plane spanned by the bivector $B$ by an angle described by its magnitude.

Reflections and orthogonal transformations

To see how the double-sided transformation law arises, note that any orthogonal transformation in $n$ dimensions is the same as at most $n$ reflections (the Cartan–Dieudonné theorem). A reflection is described in a geometric algebra by conjugation with an invertible vector. For instance, the linear map

\[ A ↦ -𝒗A𝒗^{-1}\]

reflects the multivector $A$ along the vector $𝒗$ (or across the hyperplane with normal $𝒗$).[1]

Note

Scaling each $𝒗$ by a non-zero scalar $λ$ does not affect the reflection. Therefore, a direct correspondence exists between reflections and normalised vectors $𝒗̂^2 = ±1$, modulo overall sign (since $𝒗̂$ and $-𝒗̂$ describe the same reflection).

By composing reflections as above, we can obtain any orthogonal transformation, acting as

\[ A ↦ ±RAR^{-1}\]

for some $R = 𝒗_1𝒗_2⋯𝒗_k$. The overall sign is positive for an even number of reflections (giving a proper rotation), and negative for an odd number.

Without loss of generality, we may use normalised vectors, so that the inverse is

\[ R^{-1} = 𝒗̂_k^{-1}\cdots 𝒗̂_2^{-1}𝒗̂_1^{-1} = ±\tilde{R}\]

since $𝒗̂^{-1} = ±𝒗̂$. Hence, an orthogonal transformation is described by

\[ A ↦ ±RA\tilde{R}\]

where $R$ is satisfies $R^{-1} = ±\tilde{R}$.

Rotor groups

All such multivectors satisfying $R^{-1} = ±\tilde{R}$ taken together form a group under the geometric product. This is called the pin group:

\[ \mathsf{Pin}(p, q) ≔ \big\{ R ∈ Cl(p, q) \mid R\tilde{R} = ±1 \big\}\]

There are two “pinors” for every orthogonal transformation, namely $+R$ and $-R$. Thus, the pin group forms a double cover of the orthogonal group $\mathsf{O}(p,q)$.

Furthermore, the even-grade elements of $\mathsf{Pin}(p,q)$ form a subgroup, called the spin group:

\[ \mathsf{Spin}(p, q) ≔ \big\{ R ∈ Cl_+(p, q) \mid R\tilde{R} = ±1 \big\}\]

The spin group, in turn, forms a double cover of the special orthogonal group $\mathsf{SO}(p, q)$.

Finally, the additional requirement that $R\tilde{R} = 1$ defines the restricted spinor group, or the rotor group:

\[ \mathsf{Spin}^+(p, q) ≔ \big\{ R ∈ Cl_+(p, q) \mid R\tilde{R} = 1 \big\}\]

The rotor group is a double cover of the restricted special orthogonal group $\mathsf{SO}^+(p, q)$, which is the identity-connected part of $\mathsf{SO}(p, q)$.

The takeaway is that any orthogonal transformation, including reflections, rotations, and combinations of both, can be described within geometric algebra with rotors, no matter the kind of multivector being transformed, and independent of the dimension or signature of the algebra. In particular, proper rotations are described by rotors, or even multivectors satisfying $R\tilde{R} = 1$.

The bivector subalgebra

Bivectors play a special role as the generators of rotors. Because the even subalgebra is closed under the geometric product, the exponential

\[ e^B = 1 + B + B^2/2 + ⋯ ∈ \mathsf{Spin}^+\]

of a bivector $B$ is always an even multivector, and the reverse $\tilde{}\,(e^B) = e^{-B}$ is the inverse. Therefore, $e^B ∈ \mathsf{Spin}^+$ is a rotor; and indeed, any rotor $R ∈ \mathsf{Spin}^+$ is of the form

\[R = e^B\]

for some bivector $B$.

Bivector Lie algebra

Formally, bivectors form a Lie algebra under the commutator product $A × B ≔ \frac12(AB - BA)$. Indeed, this demonstrates a Lie group–Lie algebra correspondence between the rotor group $\mathsf{Spin}^+$ and bivectors equipped with $×$.

  • 1To see this, consider the case where $A$ is a vector parallel or orthogonal to $𝒗$.
+Rotors · GeometricAlgebra.jl
GitHub

Rotors

Rotors are multivectors which describe proper rotations. The rotor formalism provides an extremely uniform, elegant and efficient description of rotations. For motivation, it is helpful to consider rotations in simpler algebras.

In the complex plane, a complex number $z ∈ ℂ$ is rotated about the origin with the mapping $z ↦ e^{iθ}z$. Similarly, a quaternion $q ∈ ℍ$ is rotated about an axis $n$ with $q ↦ e^{n/2}qe^{-n/2}$. Indeed, the double-sided transformation law

\[A ↦ e^{B/2}Ae^{-B/2}\]

is general to both $ℂ$ and $ℍ$, and in fact applies to geometric algebras of any dimension. Specifically, the rotor $R = e^{B/2}$ describes a rotation in the plane spanned by the bivector $B$ by an angle described by its magnitude.

Reflections and orthogonal transformations

To see how the double-sided transformation law arises, note that any orthogonal transformation in $n$ dimensions is the same as at most $n$ reflections (the Cartan–Dieudonné theorem). A reflection is described in a geometric algebra by conjugation with an invertible vector. For instance, the linear map

\[ A ↦ -𝒗A𝒗^{-1}\]

reflects the multivector $A$ along the vector $𝒗$ (or across the hyperplane with normal $𝒗$).[1]

Note

Scaling each $𝒗$ by a non-zero scalar $λ$ does not affect the reflection. Therefore, a direct correspondence exists between reflections and normalised vectors $𝒗̂^2 = ±1$, modulo overall sign (since $𝒗̂$ and $-𝒗̂$ describe the same reflection).

By composing reflections as above, we can obtain any orthogonal transformation, acting as

\[ A ↦ ±RAR^{-1}\]

for some $R = 𝒗_1𝒗_2⋯𝒗_k$. The overall sign is positive for an even number of reflections (giving a proper rotation), and negative for an odd number.

Without loss of generality, we may use normalised vectors, so that the inverse is

\[ R^{-1} = 𝒗̂_k^{-1}\cdots 𝒗̂_2^{-1}𝒗̂_1^{-1} = ±\tilde{R}\]

since $𝒗̂^{-1} = ±𝒗̂$. Hence, an orthogonal transformation is described by

\[ A ↦ ±RA\tilde{R}\]

where $R$ is satisfies $R^{-1} = ±\tilde{R}$.

Rotor groups

All such multivectors satisfying $R^{-1} = ±\tilde{R}$ taken together form a group under the geometric product. This is called the pin group:

\[ \mathsf{Pin}(p, q) ≔ \big\{ R ∈ Cl(p, q) \mid R\tilde{R} = ±1 \big\}\]

There are two “pinors” for every orthogonal transformation, namely $+R$ and $-R$. Thus, the pin group forms a double cover of the orthogonal group $\mathsf{O}(p,q)$.

Furthermore, the even-grade elements of $\mathsf{Pin}(p,q)$ form a subgroup, called the spin group:

\[ \mathsf{Spin}(p, q) ≔ \big\{ R ∈ Cl_+(p, q) \mid R\tilde{R} = ±1 \big\}\]

The spin group, in turn, forms a double cover of the special orthogonal group $\mathsf{SO}(p, q)$.

Finally, the additional requirement that $R\tilde{R} = 1$ defines the restricted spinor group, or the rotor group:

\[ \mathsf{Spin}^+(p, q) ≔ \big\{ R ∈ Cl_+(p, q) \mid R\tilde{R} = 1 \big\}\]

The rotor group is a double cover of the restricted special orthogonal group $\mathsf{SO}^+(p, q)$, which is the identity-connected part of $\mathsf{SO}(p, q)$.

The takeaway is that any orthogonal transformation, including reflections, rotations, and combinations of both, can be described within geometric algebra with rotors, no matter the kind of multivector being transformed, and independent of the dimension or signature of the algebra. In particular, proper rotations are described by rotors, or even multivectors satisfying $R\tilde{R} = 1$.

The bivector subalgebra

Bivectors play a special role as the generators of rotors. Because the even subalgebra is closed under the geometric product, the exponential

\[ e^B = 1 + B + B^2/2 + ⋯ ∈ \mathsf{Spin}^+\]

of a bivector $B$ is always an even multivector, and the reverse $\tilde{}\,(e^B) = e^{-B}$ is the inverse. Therefore, $e^B ∈ \mathsf{Spin}^+$ is a rotor; and indeed, any rotor $R ∈ \mathsf{Spin}^+$ is of the form

\[R = e^B\]

for some bivector $B$.

Bivector Lie algebra

Formally, bivectors form a Lie algebra under the commutator product $A × B ≔ \frac12(AB - BA)$. Indeed, this demonstrates a Lie group–Lie algebra correspondence between the rotor group $\mathsf{Spin}^+$ and bivectors equipped with $×$.

  • 1To see this, consider the case where $A$ is a vector parallel or orthogonal to $𝒗$.
diff --git a/dev/theory/special/index.html b/dev/theory/special/index.html index 89f0184..88a005f 100644 --- a/dev/theory/special/index.html +++ b/dev/theory/special/index.html @@ -1,5 +1,5 @@ -Inverses, Roots and Logarithms · GeometricAlgebra.jl
GitHub

Inverses, Roots and Logarithms

In general, finding the inverse $A^{-1}$, square root $\sqrt{A}$ or logarithm $\log A$ of a general multivector $A$ is difficult. However, for certain cases, explicit formulae exist.

Multivector inverses

Any multivector $A$ has either no inverse or exactly one inverse $A^{-1}$ such that $AA^{-1} = A^{-1}A = 1$.

Explicit formulae for multivector inverses

For any metric in up to five dimensions, explicit formulae exist for the inverse of a multivector $A$. The implementation used in GeometricAlgebra.jl is mainly based on [3] and is described here.

For a multivector $A ∈ Cl(ℝ^d, ·)$ with metric $·$ in $d$ dimensions, let:

\[[A]_K = \sum_{k=0}^d ⟨A⟩_k · \begin{cases} +Inverses, Roots and Logarithms · GeometricAlgebra.jl

GitHub

Inverses, Roots and Logarithms

In general, finding the inverse $A^{-1}$, square root $\sqrt{A}$ or logarithm $\log A$ of a general multivector $A$ is difficult. However, for certain cases, explicit formulae exist.

Multivector inverses

Any multivector $A$ has either no inverse or exactly one inverse $A^{-1}$ such that $AA^{-1} = A^{-1}A = 1$.

Explicit formulae for multivector inverses

For any metric in up to five dimensions, explicit formulae exist for the inverse of a multivector $A$. The implementation used in GeometricAlgebra.jl is mainly based on [3] and is described here.

For a multivector $A ∈ Cl(ℝ^d, ·)$ with metric $·$ in $d$ dimensions, let:

\[[A]_K = \sum_{k=0}^d ⟨A⟩_k · \begin{cases} -1 & \text{if } k ∈ K \\ +1 & \text{otherwise} -.\end{cases}\]

Special caseFormula
$A^2 ∈ ℝ$$A^{-1} = \frac{A}{A^2}$
$d = 3$$A^{-1} = \frac{ĀÂÃ}{AĀÂÃ}$
$d = 4$$A^{-1} = \frac{B}{AB}, B = Ā[AĀ]_{3,4}$
$d = 5$$A^{-1} = \frac{B}{AB}, B = ĀÂÃ[AĀÂÃ]_{1,4}$

Formulae for multivector square roots

Special caseFormula
$A^2 ∈ ℝ, A^2 < 0$$\sqrt{A} = \frac{A + λ}{\sqrt{2λ}}, λ = \sqrt{-A^2}$
$A^2 ∈ ℝ, A^2 > 0, I^2 = -1, AI = IA$$\sqrt{A} = \frac{A + Iλ}{(1 + I)\sqrt{λ}}, λ = \sqrt{A^2}$
+.\end{cases}\]

Special caseFormula
$A^2 ∈ ℝ$$A^{-1} = \frac{A}{A^2}$
$d = 3$$A^{-1} = \frac{ĀÂÃ}{AĀÂÃ}$
$d = 4$$A^{-1} = \frac{B}{AB}, B = Ā[AĀ]_{3,4}$
$d = 5$$A^{-1} = \frac{B}{AB}, B = ĀÂÃ[AĀÂÃ]_{1,4}$

Formulae for multivector square roots

Special caseFormula
$A^2 ∈ ℝ, A^2 < 0$$\sqrt{A} = \frac{A + λ}{\sqrt{2λ}}, λ = \sqrt{-A^2}$
$A^2 ∈ ℝ, A^2 > 0, I^2 = -1, AI = IA$$\sqrt{A} = \frac{A + Iλ}{(1 + I)\sqrt{λ}}, λ = \sqrt{A^2}$