From 47f89c55fe029242f4932679cd63ac893f39e8e5 Mon Sep 17 00:00:00 2001 From: dev Date: Tue, 7 Oct 2025 14:30:23 +0530 Subject: [PATCH 1/3] Add classical and quantum Hamiltonian functions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - classical_hamiltonian: Computes H = (momentum² / 2 × mass) + potential_energy - quantum_hamiltonian_1d: Builds 1D Hamiltonian matrix using finite difference discretization - Includes parameter validation and optional rounding for quantum matrix - Docstrings with detailed description, formula, and examples added --- physics/hamiltonian.py | 128 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 physics/hamiltonian.py diff --git a/physics/hamiltonian.py b/physics/hamiltonian.py new file mode 100644 index 000000000000..cf39f96a726e --- /dev/null +++ b/physics/hamiltonian.py @@ -0,0 +1,128 @@ +""" +Functions to calculate the Hamiltonian in both classical and quantum mechanics. + +Overview: + The Hamiltonian represents the total energy of a system. + + - In classical mechanics, it is the sum of kinetic and potential energies. + + - In quantum mechanics, it becomes an operator acting on the wavefunction ψ(x), describing how the system evolves in time. + +This module includes: + - classical_hamiltonian(): return total energy for given mass, momentum, and potential. + - quantum_hamiltonian_1d(): Builds a 1D Hamiltonian matrix for numerical quantum systems. +""" + +import numpy as np + + +def classical_hamiltonian(mass: float, momentum: float, potential_energy: float) -> float: + """ + Calculate the classical Hamiltonian (total energy) of a particle. + + The Hamiltonian(H) represents the total energy of the system: + H = (momentum² / (2 × mass)) + potential_energy + + Parameters: + mass (float): Mass of the particle (must be positive). + momentum (float): Linear momentum of the particle. + potential_energy (float): Potential energy of the particle. + + Returns: + float: Total energy (Hamiltonian) of the particle. + + Examples: + >>> classical_hamiltonian(1.0, 2.0, 5.0) + 7.0 + >>> classical_hamiltonian(2.0, 3.0, 1.0) + 3.25 + >>> classical_hamiltonian(1.0, 0.0, 10.0) + 10.0 + >>> classical_hamiltonian(1.0, 2.0, 0.0) + 2.0 + """ + if mass <= 0: + raise ValueError("Mass must be a positive value.") + return (momentum ** 2) / (2 * mass) + potential_energy + + +def quantum_hamiltonian_1d( + mass: float, + hbar: float, + potential_energy_array: np.ndarray, + grid_spacing: float, + round_to: int | None = None +) -> np.ndarray: + """ + Construct the 1-D quantum Hamiltonian matrix for a particle in given potential. + + Description: + In quantum mechanics, the Hamiltonian (H) represents the total energy + of a particle, combining both kinetic and potential energy components. + For a particle of mass m in one spatial dimension, it is defined as: + + H = - (ħ² / 2m) * (d²/dx²) + V(x) + + - The first term is the kinetic energy operator. + - The second term is the potential energy V(x). + + Using the *finite difference method*, the second derivative is approximated by: + d²ψ/dx² ≈ (ψ[i+1] - 2ψ[i] + ψ[i-1]) / (Δx²) + + This turns the continuous operator into a discrete matrix. + + Formula: + H[i, i] = (ħ² / (m × Δx²)) + V[i] + H[i, i±1] = - (ħ² / (2m × Δx²)) + + Parameters: + mass (float): Mass of the particle. (must be positive) + hbar (float): Reduced Planck constant. (must be positive) + potential_energy_array (np.ndarray): Potential energy values V(x) at each grid point. + grid_spacing (float): Distance between consecutive grid points Δx. (must be positive) + round_to (int | None): Number of decimal places to round the matrix to. + If None (default), no rounding is applied. + + Returns: + np.ndarray: The discrete Hamiltonian matrix representing the total energy operator. + + Examples: + >>> import numpy as np + >>> potential = np.array([0.0, 0.0, 0.0]) + >>> quantum_hamiltonian_1d(1.0, 1.0, potential, 1.0) + array([[ 1. , -0.5, 0. ], + [-0.5, 1. , -0.5], + [ 0. , -0.5, 1. ]]) + >>> potential = np.array([1.0, 2.0, 3.0]) + >>> quantum_hamiltonian_1d(2.0, 1.0, potential, 0.5) + array([[ 3., -1., 0.], + [-1., 4., -1.], + [ 0., -1., 5.]]) + """ + if any(val <= 0 for val in (mass, hbar, grid_spacing)): + raise ValueError("mass, hbar, and grid_spacing must be positive values.") + + num_points = len(potential_energy_array) + kinetic_prefactor = hbar**2 / (2 * mass * grid_spacing**2) + + diagonal = np.full(num_points, 2) + off_diagonal = np.ones(num_points - 1) + + kinetic_matrix = kinetic_prefactor * ( + np.diag(diagonal) + - np.diag(off_diagonal, 1) + - np.diag(off_diagonal, -1) + ) + + potential_matrix = np.diag(potential_energy_array) + total_hamiltonian = kinetic_matrix + potential_matrix + + if round_to is not None: + total_hamiltonian = np.round(total_hamiltonian, round_to) + + return total_hamiltonian + +if __name__ == "__main__": + import doctest + + doctest.testmod(verbose=True) From bf5f3c1cc6a75ab5be9b22ee6509ea463eef214e Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 7 Oct 2025 09:24:14 +0000 Subject: [PATCH 2/3] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- physics/hamiltonian.py | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/physics/hamiltonian.py b/physics/hamiltonian.py index cf39f96a726e..7ea345327390 100644 --- a/physics/hamiltonian.py +++ b/physics/hamiltonian.py @@ -16,7 +16,9 @@ import numpy as np -def classical_hamiltonian(mass: float, momentum: float, potential_energy: float) -> float: +def classical_hamiltonian( + mass: float, momentum: float, potential_energy: float +) -> float: """ Calculate the classical Hamiltonian (total energy) of a particle. @@ -43,7 +45,7 @@ def classical_hamiltonian(mass: float, momentum: float, potential_energy: float) """ if mass <= 0: raise ValueError("Mass must be a positive value.") - return (momentum ** 2) / (2 * mass) + potential_energy + return (momentum**2) / (2 * mass) + potential_energy def quantum_hamiltonian_1d( @@ -51,7 +53,7 @@ def quantum_hamiltonian_1d( hbar: float, potential_energy_array: np.ndarray, grid_spacing: float, - round_to: int | None = None + round_to: int | None = None, ) -> np.ndarray: """ Construct the 1-D quantum Hamiltonian matrix for a particle in given potential. @@ -109,9 +111,7 @@ def quantum_hamiltonian_1d( off_diagonal = np.ones(num_points - 1) kinetic_matrix = kinetic_prefactor * ( - np.diag(diagonal) - - np.diag(off_diagonal, 1) - - np.diag(off_diagonal, -1) + np.diag(diagonal) - np.diag(off_diagonal, 1) - np.diag(off_diagonal, -1) ) potential_matrix = np.diag(potential_energy_array) @@ -122,6 +122,7 @@ def quantum_hamiltonian_1d( return total_hamiltonian + if __name__ == "__main__": import doctest From 1ebfc341735e5f0ebff3c68486cdc940b6371781 Mon Sep 17 00:00:00 2001 From: dev Date: Thu, 9 Oct 2025 15:24:57 +0530 Subject: [PATCH 3/3] fix: correct pre-commit and ruff issues --- physics/hamiltonian.py | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/physics/hamiltonian.py b/physics/hamiltonian.py index 7ea345327390..0de9ae92ac02 100644 --- a/physics/hamiltonian.py +++ b/physics/hamiltonian.py @@ -6,11 +6,14 @@ - In classical mechanics, it is the sum of kinetic and potential energies. - - In quantum mechanics, it becomes an operator acting on the wavefunction ψ(x), describing how the system evolves in time. + - In quantum mechanics, it becomes an operator acting on the wavefunction ψ(x), + describing how the system evolves in time. This module includes: - - classical_hamiltonian(): return total energy for given mass, momentum, and potential. - - quantum_hamiltonian_1d(): Builds a 1D Hamiltonian matrix for numerical quantum systems. + - classical_hamiltonian(): return total energy for given mass, momentum, + and potential. + - quantum_hamiltonian_1d(): Builds a 1D Hamiltonian matrix for numerical + quantum systems. """ import numpy as np @@ -23,7 +26,7 @@ def classical_hamiltonian( Calculate the classical Hamiltonian (total energy) of a particle. The Hamiltonian(H) represents the total energy of the system: - H = (momentum² / (2 × mass)) + potential_energy + H = (momentum² / (2 * mass)) + potential_energy Parameters: mass (float): Mass of the particle (must be positive). @@ -74,19 +77,22 @@ def quantum_hamiltonian_1d( This turns the continuous operator into a discrete matrix. Formula: - H[i, i] = (ħ² / (m × Δx²)) + V[i] - H[i, i±1] = - (ħ² / (2m × Δx²)) + H[i, i] = (ħ² / (m * Δx²)) + V[i] + H[i, i±1] = - (ħ² / (2m * Δx²)) Parameters: mass (float): Mass of the particle. (must be positive) hbar (float): Reduced Planck constant. (must be positive) - potential_energy_array (np.ndarray): Potential energy values V(x) at each grid point. - grid_spacing (float): Distance between consecutive grid points Δx. (must be positive) + potential_energy_array (np.ndarray): Potential energy values V(x) + at each grid point. + grid_spacing (float): Distance between consecutive grid points Δx. + (must be positive) round_to (int | None): Number of decimal places to round the matrix to. If None (default), no rounding is applied. Returns: - np.ndarray: The discrete Hamiltonian matrix representing the total energy operator. + np.ndarray: The discrete Hamiltonian matrix representing + the total energy operator. Examples: >>> import numpy as np