Crate perplex_num

perplex_num

Overview

perplex_num is a Rust crate that provides an implementation of perplex numbers, based on the numerical abstractions of the num_traits crate. This library supports various mathematical functions such as pow, sqrt, exp, ln, sinh, sin, cosh, and tan. Additionally, the crate offers a hyperbolic polar form for representing and manipulating numbers in the hyperbolic plane, as well as a matrix form representation feature based on nalgebra.

For an in-depth explanation (including visualizations) of perplex numbers and how they integrate with the crate’s modules, see the Perplex Number Description in the repository.

Features

• The Perplex struct is equipped with a comprehensive set of common mathematical operations, courtesy of std::ops and num_traits.
• Emulating the functionality of nalgebra::Complex, the Perplex struct mirrors most functions found in the num_complex crate, maintaining consistent naming conventions.
• It supports the hyperbolic polar form across all sectors of the plane.
• The matrix representation feature is based upon the robust foundation of nalgebra::Matrix.

Usage

Installation

cargo add perplex_num or add this to Cargo.toml:

[dependencies]
perplex_num = "0.1"

The matrix feature is enabled by default, which adds the nalgebra crate as a dependency. This can be disabled with:

[dependencies.perplex_num]
perplex_num = "0.1"
default-features = false

Examples

The examples directory contains various practical demonstrations of how to use the perplex_num crate. These examples not only illustrate the usage of perplex numbers but also show how to produce visualizations as seen in the Perplex Number Description.

For instance, examples/visualize_functions.rs is executed by the following command:

cargo run --example visualize_functions

This will generate an image that depicts the behavior of functions like sinh, cos, inv, and exp when applied to perplex numbers.

Creating a Perplex Number and Performing Operations

Here’s a quick example of how to get started with creating a perplex number and performing basic operations:

use perplex_num::Perplex;

fn main() {
    // Create a Perplex number with real part 1.0 and hyperbolic part 0.5
    let z = Perplex::new(1.0, 0.5);
    // Calculate the hyperbolic sine of the perplex number
    let z_sinh = z.sinh();
    // Raise the perplex number or it's inverse to the power of 2
    let z_squared = z.powu(2);
    let z_inv_squared = z.powi(-2).expect("z is invertible");

    println!("The hyperbolic sine of {} is {:.5}", z, z_sinh);
    println!("{} raised to the power of 2 is {:.3}", z, z_squared);
    println!("{} raised to the power of -2 is {:.3}", z, z_inv_squared);
}

Coverage

Test coverage report is generated with cargo tarpaulin. Invoke it with:

cargo tarpaulin --verbose --all-targets --skip-clean --exclude-files "examples/*.rs" "benches/*.rs"

Compatibility

The perplex_num crate is tested for rustc 1.76.

Bibliography

• The Mathematics of Minkowski Space-Time
• Hyperbolic trigonometry in two-dimensional space-time geometry
• Fundamental Theorems of Algebra for the Perplexes
• Introduction to Hybrid Numbers
• New characterizations of the ring of the split-complex numbers and the field C of complex numbers and their comparative analyses

Structs

• HyperbolicPolar
  Represents a perplex number in hyperbolic polar form.
• Perplex
  The Perplex struct is a representation of hyperbolic numbers, also known as split-complex numbers, which consist of two components: a real part (t) and a hyperbolic part (x). These components correspond to the time and space coordinates in Minkowski space-time, respectively. See Sec. 4.1 Geometrical Representation of Hyperbolic Numbers in The Mathematics of Minkowski Space-Time. The implementation is generic over a type T, which allows it to be used with different numeric types (i.e., f32 or f64).

Enums

• HyperbolicSector
  Represents the sector of the hyperbolic plane a perplex number is in.

Type Aliases

• PerplexMatrixForm
  A type alias for a 2x2 matrix from nalgebra, representing a perplex number as a matrix.