devela/num/

power.rs

//
//
//! The triangle of power.
//
// TOC
// - struct Tp
// - impls
// - docs
//
// TODO
// - MAKE TESTS
// - finish integers
// - check formula of apow ? is it e times pth root of p? or eth rooth of p?
//
// - review documentation
// - Distinguishing Rotation Groups from Operand Order
//   - Static Operand Order: Defines how a function is structured (bep, pbe, etc.) 6 total
//   - Rotation Group (lane): Defines which 3-function cycle a function belongs to. 2 total
//   - Cycle Shift Order: Defines the modulo-3 operand cycling. 2 total: shr and shl
//
// Make a list of 6 answers of the form: (use the right letters, b e p)
// - The root is the answer to: Which number should we raise to the power b to get c ? (a=c√b),
// - the log is the answer to: To which power should we raise the number a to get c ? (b=logac).
// - pow:
// - apow:
// - aroot:
// - alog:
//
//
// IMPROVE
// - I'd like to clarify the first doc sentence of the functions. specially the anti- ones
// - maybe have 2 alternative ways of defining them, a heading and a subheading...
//
// NOTE: CHAT: https://chatgpt.com/c/67be2874-162c-8007-840c-681d8ce6979e

#![allow(clippy::empty_line_after_doc_comments, unused)]

use crate::unwrap;
#[cfg(_float··)]
use crate::ExtFloat;
#[cfg(_int··)]
use crate::Int;

/// **The Triangle of Power**
///
/// This struct formalizes the six fundamental transformations that interrelate exponentiation,
/// roots, and logarithms. These operations are not independent but form a structured system of
/// shifts and rotations, governed by underlying symmetries. Each function belongs to one of two
/// interwoven three-function cycles, with structured transformations that preserve relationships
/// between base, exponent, and power.
///
/// The system follows a modular shift structure, where functions transition through well-defined
/// rotations (`shr` and `shl`) or switch between cycles through selective shifts. This framework
/// does not introduce new computations but instead exposes the inherent structure of scaling
/// operations, making explicit the relationships that underlie exponentiation.
///
//
// NOTE: ↑ very good
// CHECK ↓
//
/// ## Structure and Transformations
///
/// The six operations are arranged into two distinct three-function cycles, each forming a closed loop under cyclic shifts.
/// Functions transition within their cycle using forward (`shr`) or backward (`shl`) shifts, while selective shifts allow
/// movement between cycles. These relationships define the full space of exponentiation-like transformations.
///
/// ### **Rotation Groups**
///
/// Each function belongs to one of two interwoven three-function cycles:
///
/// - **Exponentiation-Logarithm Cycle**: `pow → apow → log → pow`
/// - **Root-Antilogarithm Cycle**: `root → aroot → alog → root`
///
/// Within each cycle, functions are related by **modular shift transformations**:
///
/// | Function | Static Operand Order | Forward Shift (`shr`) | Backward Shift (`shl`) | Selective Shift |
/// |-------------|----------------|------------------|------------------|------------------|
/// | `pow`  | `(bep)` | `apow (epb)` | `log (pbe)` | `root (peb)` |
/// | `apow` | `(epb)` | `log (pbe)` | `pow (bep)` | `aroot (bpe)` |
/// | `log` | `(pbe)` | `alog (ebp)` | `pow (bep)` | `apow (epb)` |
/// | `root` | `(bpe)` | `aroot (peb)` | `alog (ebp)` | `apow (epb)` |
/// | `aroot` | `(peb)` | `alog (ebp)` | `root (bpe)` | `pow (bep)` |
/// | `alog` | `(ebp)` | `pow (bep)` | `root (bpe)` | `aroot (bpe)` |
///
///
/// ### **Shift Transformations**
///
/// Each function is connected to others by structured shifts:
///
/// - **Cycle shifts (`shr`, `shl`)** maintain movement within the same rotation group.
/// - **Selective shifts (`X << Y == Z >>`) enable transitions between cycles.**
///
/// These shifts behave modularly, ensuring all transformations preserve valid operand relationships.
///
/// By formalizing these relationships, this struct provides a systematic way to express, explore, and manipulate
/// exponentiation-based transformations, making explicit the structure that underlies their behavior.


// # Meta operations
//
// Operations can be classified by **rearranging** their three operands
// using the **⊕ meta-operator**:
//
// - `pow   = base ⊕ exponent = power` (bep)
// - `apow  = exponent ⊕ power = base` (epb)
// - `root  = power ⊕ exponent = base` (peb)
// - `aroot = base ⊕ power = exponent` (bpe)
// - `log   = power ⊕ base = exponent` (pbe)
// - `alog  = exponent ⊕ base = power` (ebp)

pub struct Tp<T>(T);

/* impls */

macro_rules! impl_tp {
    () => {
        impl_tp![int i32|"_int_i32"];
        impl_tp![float f32|"_float_f32", f64|"_float_f64"];
    };
    (float $($T:ty | $feat:literal),+) => { $( impl_tp![@float $T|$feat]; )+ };
    (int   $($T:ty | $feat:literal),+) => { $( impl_tp![@int $T|$feat]; )+ };
    (@float $T:ty | $feat:literal) => {
        impl Tp<$T> {
            #[doc = POW![]]
            #[cfg(feature = $feat)]
            #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = $feat)))]
            pub fn pow(&self, exponent: Self) -> Self {
                Self(self.0.powf(exponent.0))
            }

            #[doc = APOW![]]
            #[cfg(feature = $feat)]
            #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = $feat)))]
            pub fn apow(&self, power: Self) -> Self {
                Self(power.0.powf(self.0))
                // Self(self.0.powf(power.0.recip())) // is it the same?
            }

            #[doc = ROOT![]]
            #[cfg(feature = $feat)]
            #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = $feat)))]
            pub fn root(&self, exponent: Self) -> Self {
                Self(self.0.powf(exponent.0.recip()))
            }

            #[doc = AROOT![]]
            #[cfg(feature = $feat)]
            #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = $feat)))]
            pub fn aroot(&self, power: Self) -> Self {
                Self(power.0.powf(self.0.recip()))
            }

            #[doc = LOG![]]
            #[cfg(feature = $feat)]
            #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = $feat)))]
            pub fn log(&self, base: Self) -> Self {
                Self(self.0.log(base.0))
            }

            #[doc = ALOG![]]
            #[cfg(feature = $feat)]
            #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = $feat)))]
            pub fn alog(&self, base: Self) -> Self {
                Self(base.0.powf(self.0))
            }
        }
    };
    (@int $T:ty | $feat:literal) => {
        impl Tp<$T> {
            #[doc = POW![]]
            #[cfg(feature = $feat)]
            #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = $feat)))]
            // UNDERSTAND: what happens if exponent is negative?, pow fn requires u32
            pub const fn pow(&self, exponent: Self) -> Self {
                Self(self.0.pow(exponent.0 as u32))
            }

            #[doc = APOW![]]
            #[cfg(feature = $feat)]
            #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = $feat)))]
            pub fn apow(&self, power: Self) -> Self {
                Self(power.0.pow(self.0 as u32))
                // Self(self.0.pow(power.0.recip())) // is the same?
            }

            #[doc = ROOT![]]
            #[cfg(feature = $feat)]
            #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = $feat)))]
            pub const fn root(&self, exponent: Self) -> Self {
                // IMPROVE make checked conversions... return result?
                Self(unwrap![ok Int(self.0).root_floor(exponent.0 as u32)].0)
            }

            // #[doc = AROOT![]]
            // #[cfg(feature = $feat)]
            // #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = $feat)))]
            // pub fn aroot(&self, power: Self) -> Self {
            //     Self(power.0.powf(self.0.recip()))
            // }
            //
            // #[doc = LOG![]]
            // #[cfg(feature = $feat)]
            // #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = $feat)))]
            // pub fn log(&self, base: Self) -> Self {
            //     Self(self.0.log(base.0))
            // }
            //
            // #[doc = ALOG![]]
            // #[cfg(feature = $feat)]
            // #[cfg_attr(feature = "nightly_doc", doc(cfg(feature = $feat)))]
            // pub fn alog(&self, base: Self) -> Self {
            //     Self(base.0.powf(self.0))
            // }
        }
    };
}
impl_tp![];

/* docs */

crate::CONST! {
    POW = "Computes `power` by raising (`self` as base) to `exponent`.\n\n
- math: $ b^e = p $
- func: `pow(base, exponent) = base^exponent = power`
- meta: `base ⊕ exponent = power`
- symb: `^` → `b^e=p`

# Pairs by
|    self    |   param    |   result   |  shr  |  shl  |
|:----------:|:----------:|:----------:|:-----:|:-----:|
| = base     | = exponent | = power    |  >>   |  <<   |
| aroot      | root       | alog       | apow  | log   |
";

    APOW = "Computes `base`, such that raising it to (`self` as exponent) produces `power`.\n\n
- math: $ e \\sqrt[p]{p} = b $ ⟺ $ p^{1/e} = b $
- func: `apow(exponent, power) = power^(1/exponent) = base`
- meta: `exponent ⊕ power = base`
- symb: `^` → `e^p=b`
# Pairs by
|    self    |   param    |   result   |  shr  |  shl  |
|:----------:|:----------:|:----------:|:-----:|:-----:|
| = exponent | = power    | = base     |  >>   |  <<   |
| alog       | aroot      | root       | log   | pow   |
";

    ROOT = "Computes `base`, such that raising it to `exponent` produces (`self` as power).\n\n
- math: $ p^{(1/e)} = b $ ⟺ $ e \\sqrt[p]{p} = b $
- func: `root(power, exponent) = power^(1/exponent) = base`
- meta: `power ⊕ exponent = base`
- symb: `√` → `p√e=b`
# Pairs by
|    self    |   param    |   result   |  shr  |  shl  |
|:----------:|:----------:|:----------:|:-----:|:-----:|
| = power    | = exponent | = base     | >>    | <<    |
| log        | pow        | apow       | alog  | aroot |
";

    AROOT = "Computes `exponent`, such that raising (`self` as base) to it produces `power`.\n\n
- math: $ b^{(1/p)} = e $
- func: `aroot(base, power) = exponent`
- meta: `base ⊕ power = exponent`
- symb: `√` → `b√p=e`
# Pairs by
|    self    |   param    |   result   |      shr      |      shl      |
|:----------:|:----------:|:----------:|:-------------:|:-------------:|
| = base     | = power    | = exponent | (b>> p>> e>>) | (b<< p<< e<< |
| pow        | apow       | log        | root          | root          |
";

// - log:   (>>) p@b=e (p:<< b:== e:>> to alog)
// - alog:  (<<) e@b=p (e:>> b:== e:<< to log)

    LOG = "Computes `exponent` as the logarithm of (`self` as power) with respect to `base`.\n\n
- math: $ \\log_b(p) = e $
- func: `log(power, base) = log_base(power) = exponent`
- meta: `power ⊕ base = exponent`
- symb: `@` → `p@b=e`
# Pairs by
|    self    |   param    |   result   |    reverse    |      shl      |
|:----------:|:----------:|:----------:|:-------------:|:-------------:|
| = power    | = base     | = exponent | (??)          | (b<< e<< p<<) |
| root       | alog       | aroot      | alog ??       | log           |
";

    ALOG = "Computes `power`, using (`self` as exponent) and `base`.\n\n
- math: $ b^e = p $
- func: `alog(exponent, base) = base^exponent = power`
- meta: `exponent ⊕ base = power`
- symb: `@` → `e@b=p`
# Pairs by
|    self    |   param    |   result   |    reverse    |      shl      |
|:----------:|:----------:|:----------:|:-------------:|:-------------:|
| = exponent | = base     | = power    | (??)          | (b<< e<< p<<) |
| apow       | log        | pow        | log ??        | log           |
";
}
/*

# trivial (no shift)
# shr (cycles)
# shl (cycles)
# mid eq (changes direction)
# left eq (changes direction)
# right eq (changes direction)

["b== e== p=="] → bep (pow)
["b>> e>> p>>"] → epb (apow)
["b<< e<< p<<"] → pbe (log)
["b<< e== p>>"] → peb (aroot)
["b== e>> p<<"] → bpe (root)
["b>> e<< p=="] → ebp (alog)

["e== p== b=="] → epb (apow)
["e>> p>> b>>"] → pbe (log)
["e<< p<< b<<"] → bep (pow)
["e<< p== b>>"] → bpe (root)
["e== p>> b<<"] → ebp (alog)
["e>> p<< b=="] → peb (aroot)

["b== p== e=="] → bpe (root)
["b>> p>> e>>"] → ebp (alog)
["b<< p<< e<<"] → peb (aroot)
["b>> p== e<<"] → epb (apow)
["b== p<< e>>"] → bep (pow)
["b<< p>> e=="] → pbe (root)

["p== e== b=="] → peb (aroot)
["p>> e>> b>>"] → bpe (root)
["p<< e<< b<<"] → ebp (alog)
["p>> e== b<<"] → bep (pow)
["p== e<< b>>"] → pbe (log)
["p<< e>> b=="] → epb (apow)

["p== b== e=="] → pbe (log)
["p>> b>> e>>"] → bep (pow)
["p<< b<< e<<"] → epb (apow)
["p<< b== e>>"] → ebp (alog)
["p== b>> e<<"] → peb (aroot)
["p>> b<< e=="] → bpe (root)

["e== b== p=="] → ebp (alog)
["e>> b>> p>>"] → peb (aroot)
["e<< b<< p<<"] → bpe (root)
["e>> b== p<<"] → pbe (log)
["e== b<< p>>"] → epb (apow)
["e<< b>> p=="] → bep (pow)

// # Cyclic permutations
//
// Each operation is part of a **closed cycle of three elements**,
// and each function is paired with its **cyclic inverse**.
//
// - **Default cycle (`BEP` cycle, `>>` forward shift):**
//   - (… base → exponent → power → base …) (bep, epb, pbe)
// - **Reverse cycle (`PEB` cycle, `<<` backward shift):**
//   - (… power → exponent → base → power …) (peb, ebp, bpe)
// - **Unchanged (`==` elements remain static).**
//
// **Rules for shifting operations:**
// - `>>` (forward shift): `b→e`, `e→p`, `p→b`
// - `<<` (backward shift): `e→b`, `p→e`, `b→p`
//
// **Cyclic pairing structure:**
// - `pow[b⊕e=p] >> apow[e⊕p=b] >> log[p⊕b=e] >> pow …`
// - `root[p⊕e=b] >> alog[e⊕b=p] >> aroot[b⊕p=e] >> root …`
// Operations can be viewed in relation to a cycle of elements and paired
// by the reversion of their cycle.
//
// - Let's define a default cyclic order called `forward shift`, or `BEP`, denoted with `>>`:
//   - (… base → exponent → power → base → exponent → power …) (bep, epb, pbe)
// - Let's call the reverse cyclic order `backward shift`, or `PEB`, and denote with `<<`:
//   - (… power → exponent → base → power → exponent → base …) (peb, ebp, bpe)
// - Unchanged, non-cycled elements we shall denote with `==`.
//
// Using << or >> for the whole operation means all its elements are shifted accordingly:
// - `>> = b→e && e→p && p→b`
// - `<< = e→b && p→e && b→p`
//
// There are two differenciated cycles:
// - pow[b⊕e=p] >> apow[e⊕p=b] >> log[p⊕b=e] >> pow…
// - root[b⊕p=e] >> aroot[p⊕e=b] >> alog[e⊕b=p] >> root…
//
// Each function employs a static cyclic order for their operands (self, param and result),
// and a dynamic cyclic order to switch to the reverse complementary operation.
///
/// - pow:   (>>)(bep)  b^e=p (>> to apow *epb*) (<< to log *pbe*) (b<< e== p>> to root *peb*)
/// - apow:  (>>)(epb)  e^p=b (<< to pow *bep*)  (>> to log *pbe*) (e<< p== b>> to aroot *bpe*)
//
/// - root:  (<<)(bpe)  b√p=e (<< to *aroot*) (>> to alog *ebp*) (b>> p== e<< to apow *epb*)
/// - aroot: (<<)(peb)  p√e=b (>> to *root*)  (<< to alog *ebp*) (p>> e== b<< to pow *bep*)
///
/// - log:   (>>)(pbe) p@b=e (p<< b== e>> to alog *ebp*) (>> to pow *bep*)    (<< to apow *epb*)
/// - alog:  (<<)(ebp) e@b=p (e>> b== p<< to log *pbe*)  (<< to aroot *bpe* ) (>> to root *peb*)
///
/// Insights
/// - Each function has a natural shift direction (>> or <<), and belongs to a static cycle.
/// -
// NOTE: (b>> e== p<<) = eee && (e>> p== b<<) = ppp (invalid)
// NOTE: (b>> p== e<<) = ppp && (p>> e== b<<) = eee (invalid)
// NOTE: (p>> b== e<<) = bbb && (e<< b== p>>) = bbb (invalid)


/// Operations defined by the cyclic permutation of 3 elements:
///
///                          --1st symmetry--  --2nd symmetry-- --3rd symmetry--
/// - pow   = `^` → `b^e=p`  (self   = base)  (result  = power) (operand = exponent)
/// - apow  = `^` → `e^p=b`  (result = base)  (operand = power) (self    = exponent)
///
/// - aroot = `√` → `b√p=e`  (self   = base)  (result  = exponent) (operand = power)
/// - root  = `√` → `p√e=b`  (result = base)  (operand = exponent) (self    = power)
///
/// - log   = `@` → `p@b=e`  (self   = power) (result = exponent)  (operand = base)
/// - alog  = `@` → `e@b=p`  (result = power) (self   = exponent)  (operand = base)



/// Exponentiation (pow & apow)
/// - cycle: (Base → Exponent → Power)
/// - defines direct power growth.
/// - describes how multiplying a base builds a power.
///
/// Roots (root & aroot)
/// - cycle: (Power → Exponent → Base)
/// - defines extracting a base from a power.
/// - describes how extracting a base from a power requires an exponent.
///
/// Logs (log & alog)
/// - cycle: (Power → Base → Exponent)
/// - defines extracting an exponent from a power.
/// - describes how computing an exponent requires knowledge of the base and power.


/// - Switching self's role with the operand's:
///   - key idea: Inverting perspective
///   - best for: Procedural implementation
///   - pow ↔ apow, root ↔ aroot, log ↔ alog
/// - Keeping self's Role.
///   - Grouping transformations that modify the same kind of number
///   - Seeing relationships within the same type
///   - pow ↔ aroot, root ↔ log, apow ↔ alog
/// - Complementary Transformations
///   - Pairing operations that reshape structure differently
///   - Seeing deep structural similarities
///   - pow ↔ root, apow ↔ log, aroot ↔ alog
///
// ## Connecting complementary transformations
// 1. Power & Root: Internal Structure of a Base
// - Both apply an exponent, but power extends while root reduces.
// - Power is direct multiplication, root is fractional multiplication (division in exponent form).
// - They modify the internal structure of a single number without needing an external reference.
//
// 2. Apow & Log: The Scaling & Counting Perspective
// - Exponentiation (apow) determines a base given an exponent.
// - Logarithm (log) determines the exponent given a base.
// - They represent scaling from a reference point rather than modifying a single number’s structure.
//
// 3. aroot & alog: The Reference Frame Shift
// - Both find a missing component, but rather than undoing a single operation, they are about reframing.
// - aroot asks: "What base, raised to a fractional exponent, gives this radicand?"
// - alog asks: "What number, raised to this exponent, produces the base?"
// - They both invert in a relative sense—switching between fractional and exponential forms.

*/