ts-quantum
Version:
TypeScript library for quantum mechanics calculations and utilities
108 lines (107 loc) • 4.16 kB
TypeScript
/**
* State Analysis and Decomposition for Angular Momentum States
*
* Phase 1 implementation for T66: Multi-Spin Coupling and Intertwiner Implementation
* Provides functions to analyze composite angular momentum states and extract j-components.
*/
import { Complex } from '../core/types';
import { StateVector } from '../states/stateVector';
/**
* Analysis results for an angular momentum state
*/
interface AngularStateAnalysis {
/** Whether this state has angular momentum structure */
isAngularMomentum: boolean;
/** Map of j values to their component information */
components: Map<number, JComponentInfo>;
/** The j value with the largest amplitude */
dominantJ: number | null;
/** Whether this is a pure j-eigenstate or mixed superposition */
isPure: boolean;
/** Original coupling information if available */
couplingInfo?: {
j1: number;
j2: number;
originalStates?: StateVector[];
};
}
/**
* Information about a specific j-component
*/
interface JComponentInfo {
/** Angular momentum quantum number */
j: number;
/** Expected dimension (2j+1) */
dimension: number;
/** Total amplitude for this j-component */
totalAmplitude: Complex;
/** Magnitude of total amplitude */
magnitude: number;
/** Individual m-state amplitudes */
mStates: Map<number, Complex>;
/** Whether this component is present */
isPresent: boolean;
}
/**
* Enhanced state vector with j-component extraction capability
*/
interface ExtractedJComponent {
/** The extracted j-component as a pure state */
state: StateVector;
/** Angular momentum quantum number */
j: number;
/** Normalization factor applied */
normalizationFactor: number;
/** Original magnitude in composite state */
originalMagnitude: number;
}
/**
* Analyzes a StateVector to determine its angular momentum structure
*
* This is the core function that enables multi-spin coupling by identifying
* what j-components are present in a composite angular momentum state.
*
* @param state The state vector to analyze
* @param j1 First angular momentum (if known from coupling history) - optional for backwards compatibility
* @param j2 Second angular momentum (if known from coupling history) - optional for backwards compatibility
* @returns Analysis results showing j-component structure
*/
declare function analyzeAngularState(state: StateVector, j1?: number, j2?: number): AngularStateAnalysis;
/**
* Extracts a specific j-component from a composite angular momentum state
*
* This is the key function that enables multi-spin coupling by extracting
* pure j-components that can be used with existing addAngularMomenta function.
*
* @param state Composite state containing multiple j-components
* @param targetJ The j value to extract
* @param j1 First original angular momentum (optional for backwards compatibility)
* @param j2 Second original angular momentum (optional for backwards compatibility)
* @returns Extracted pure j-component state, or null if not present
*/
declare function extractJComponent(state: StateVector, targetJ: number, j1?: number, j2?: number): ExtractedJComponent | null;
/**
* Determines if a StateVector has angular momentum decomposition information
*
* @param state StateVector to check
* @returns True if state has angular momentum metadata
*/
declare function hasAngularMomentumData(state: StateVector): boolean;
/**
* Gets coupling information from a StateVector if available
*
* @param state StateVector to examine
* @returns Coupling information or null if not available
*/
declare function getCouplingInfo(state: StateVector): {
j1: number;
j2: number;
} | null;
/**
* Creates a detailed string representation of the analysis results
*
* @param analysis Analysis results from analyzeAngularState
* @returns Human-readable description
*/
declare function analysisToString(analysis: AngularStateAnalysis): string;
export { analyzeAngularState, extractJComponent, hasAngularMomentumData, getCouplingInfo, analysisToString, AngularStateAnalysis, JComponentInfo, ExtractedJComponent };