ts-quantum/dist/quantum/src/angularMomentum/core.d.ts

TypeScript library for quantum mechanics calculations and utilities

/**
 * Angular momentum operators implementation
 * Implements J₊, J₋, Jz, and J² operators for arbitrary angular momentum j
 */
import { Complex, IOperator } from '../core/types';
import { StateVector } from '../states/stateVector';
/**
 * Creates an angular momentum state |j,m⟩
 *
 * @param j Total angular momentum quantum number
 * @param m Magnetic quantum number
 * @returns The state |j,m⟩ as a StateVector
 */
export declare function createJmState(j: number, m: number): StateVector;
/**
 * Converts a state vector from computational basis to angular momentum basis
 * For j=1/2: |0⟩ -> |1/2,-1/2⟩, |1⟩ -> |1/2,1/2⟩
 *
 * @param state State vector in computational basis
 * @param j Total angular momentum quantum number
 * @returns State vector in angular momentum basis
 */
export declare function computationalToAngularBasis(state: StateVector, j: number): StateVector;
/**
 * Converts a state vector from angular momentum basis to computational basis
 * For j=1/2: |1/2,-1/2⟩ -> |0⟩, |1/2,1/2⟩ -> |1⟩
 *
 * @param state State vector in angular momentum basis
 * @param j Total angular momentum quantum number
 * @returns State vector in computational basis
 */
export declare function angularToComputationalBasis(state: StateVector, j: number): StateVector;
/**
 * Attempts to identify the basis of a state vector based on its label format
 *
 * @param state State vector to identify basis for
 * @returns 'angular' for angular momentum basis, 'computational' for computational basis,
 *          or 'unknown' if basis cannot be determined
 */
export declare function identifyBasis(state: StateVector): string;
/**
 * Creates the raising operator J₊ for given angular momentum j
 * J₊|j,m⟩ = √(j(j+1) - m(m+1)) |j,m+1⟩
 *
 * @param j Total angular momentum quantum number
 * @returns The J₊ operator as a matrix
 */
export declare function createJplus(j: number): IOperator;
/**
 * Creates the lowering operator J₋ for given angular momentum j
 * J₋|j,m⟩ = √(j(j+1) - m(m-1)) |j,m-1⟩
 *
 * @param j Total angular momentum quantum number
 * @returns The J₋ operator as a matrix
 */
export declare function createJminus(j: number): IOperator;
/**
 * Creates the z-component operator Jz for given angular momentum j
 * Jz|j,m⟩ = m|j,m⟩
 *
 * @param j Total angular momentum quantum number
 * @returns The Jz operator as a matrix
 */
export declare function createJz(j: number): IOperator;
/**
 * Creates the x-component operator Jx for given angular momentum j
 * Jx = (J₊ + J₋)/2
 *
 * @param j Total angular momentum quantum number
 * @returns The Jx operator as a matrix
 */
export declare function createJx(j: number): IOperator;
/**
 * Creates the y-component operator Jy for given angular momentum j
 * Jy = (J₊ - J₋)/(2i)
 *
 * @param j Total angular momentum quantum number
 * @returns The Jy operator as a matrix
 */
export declare function createJy(j: number): IOperator;
/**
 * Creates the total angular momentum operator J² for given j
 * J²|j,m⟩ = j(j+1)|j,m⟩
 *
 * @param j Total angular momentum quantum number
 * @returns The J² operator as a matrix
 */
export declare function createJ2(j: number): IOperator;
/**
 * Creates total angular momentum operator J² from components
 * J² = Jx² + Jy² + Jz² = J₊J₋ + Jz² - Jz = J₋J₊ + Jz² + Jz
 *
 * This is an alternative implementation that constructs J² from its components.
 * Useful for verification against createJ2().
 *
 * @param j Total angular momentum quantum number
 * @returns The J² operator as a matrix
 */
export declare function createJ2FromComponents(j: number): IOperator;
/**
 * Validates angular momentum quantum number j
 * j must be a non-negative integer or half-integer
 *
 * @param j Angular momentum quantum number to validate
 * @throws Error if j is invalid
 */
export declare function validateJ(j: number): void;
/**
 * Gets the valid m values for a given j
 * m ranges from -j to +j in integer steps
 *
 * @param j Total angular momentum quantum number
 * @returns Array of valid m values
 */
export declare function getValidM(j: number): number[];
/**
 * Checks if a given m value is valid for angular momentum j
 *
 * @param j Total angular momentum quantum number
 * @param m Magnetic quantum number to check
 * @returns true if m is valid for given j
 */
export declare function isValidM(j: number, m: number): boolean;
/**
 * Creates Wigner rotation operator D(α,β,γ) = exp(-iαJz)exp(-iβJy)exp(-iγJz)
 *
 * @param j Total angular momentum quantum number
 * @param alpha First Euler angle
 * @param beta Second Euler angle
 * @param gamma Third Euler angle
 * @returns The Wigner rotation operator
 */
export declare function createRotationOperator(j: number, alpha: number, beta: number, gamma: number): IOperator;
/**
 * Calculates expectation value ⟨j,m|O|j,m⟩ for an angular momentum operator
 *
 * @param operator Angular momentum operator to calculate expectation for
 * @param j Total angular momentum quantum number
 * @param m Magnetic quantum number
 * @returns Complex expectation value
 */
export declare function jmExpectationValue(operator: IOperator, j: number, m: number): Complex;
/**
 * Creates a coherent angular momentum state |j,θ,φ⟩
 * This is an eigenstate of the angular momentum operator pointing in the direction (θ,φ)
 *
 * @param j Total angular momentum quantum number
 * @param theta Polar angle θ in radians
 * @param phi Azimuthal angle φ in radians
 * @returns The coherent state as a StateVector
 */
export declare function createCoherentState(j: number, theta: number, phi: number): StateVector;