physics.maxwells_equations
==========================

.. py:module:: physics.maxwells_equations

.. autoapi-nested-parse::

   Maxwell's Equations Implementation

   This module provides implementations of Maxwell's four fundamental equations
   that describe the behavior of electric and magnetic fields in space and time.

   The four equations are:
   1. Gauss's law for electricity: div(E) = rho/epsilon_0
   2. Gauss's law for magnetism: div(B) = 0
   3. Faraday's law of induction: curl(E) = -dB/dt
   4. Ampère-Maxwell law: curl(B) = mu_0(J + epsilon_0*dE/dt)

   Reference: https://en.wikipedia.org/wiki/Maxwell%27s_equations

   Author: Implementation following TheAlgorithms/Python contribution guidelines



Attributes
----------

.. autoapisummary::

   physics.maxwells_equations.SPEED_OF_LIGHT
   physics.maxwells_equations.VACUUM_PERMEABILITY
   physics.maxwells_equations.VACUUM_PERMITTIVITY
   physics.maxwells_equations.c


Functions
---------

.. autoapisummary::

   physics.maxwells_equations.ampere_maxwell_law
   physics.maxwells_equations.electromagnetic_wave_impedance
   physics.maxwells_equations.electromagnetic_wave_speed
   physics.maxwells_equations.energy_density_electromagnetic
   physics.maxwells_equations.faraday_law
   physics.maxwells_equations.gauss_law_electric
   physics.maxwells_equations.gauss_law_magnetic
   physics.maxwells_equations.poynting_vector_magnitude


Module Contents
---------------

.. py:function:: ampere_maxwell_law(magnetic_field_circulation: float, enclosed_current: float, electric_flux_change_rate: float, permeability: float = VACUUM_PERMEABILITY, permittivity: float = VACUUM_PERMITTIVITY) -> bool

   Ampère-Maxwell law: curl(B) = mu_0(J + epsilon_0*dE/dt)

   In integral form: ∮B·dl = mu_0(I_enclosed + epsilon_0*dPhi_E/dt)

   This law relates magnetic fields to electric currents and changing electric fields.
   Maxwell's addition of the displacement current term (epsilon_0*dE/dt) was crucial
   for predicting electromagnetic waves.

   Args:
       magnetic_field_circulation: Line integral of B around closed loop (T·m)
       enclosed_current: Current passing through surface bounded by loop (A)
       electric_flux_change_rate: Rate of change of electric flux (V·m/s)
       permeability: Permeability of the medium (H/m), defaults to vacuum
       permittivity: Permittivity of the medium (F/m), defaults to vacuum

   Returns:
       bool: True if Ampère-Maxwell law is satisfied within numerical tolerance

   Raises:
       ValueError: If permeability or permittivity is non-positive

   Example:
       >>> ampere_maxwell_law(1.256e-6, 1.0, 0.0)
       True
       >>> ampere_maxwell_law(2.512e-6, 2.0, 0.0)
       True
       >>> ampere_maxwell_law(1.11e-5, 0.0, 1.0e12)
       True


.. py:function:: electromagnetic_wave_impedance(permeability: float = VACUUM_PERMEABILITY, permittivity: float = VACUUM_PERMITTIVITY) -> float

   Calculate the impedance of electromagnetic waves in a medium.

   The impedance Z_0 = sqrt(mu/epsilon) determines the ratio of electric to magnetic
   field strength in an electromagnetic wave.

   Args:
       permeability: Permeability of the medium (H/m)
       permittivity: Permittivity of the medium (F/m)

   Returns:
       float: Wave impedance of the medium (Ω - ohms)

   Raises:
       ValueError: If permeability or permittivity is non-positive

   Example:
       >>> abs(electromagnetic_wave_impedance() - 376.73) < 0.01
       True
       >>> impedance = electromagnetic_wave_impedance(
       ...     2*VACUUM_PERMEABILITY, VACUUM_PERMITTIVITY
       ... )
       >>> abs(impedance - 532.0) < 1.0
       True


.. py:function:: electromagnetic_wave_speed(permeability: float = VACUUM_PERMEABILITY, permittivity: float = VACUUM_PERMITTIVITY) -> float

   Calculate the speed of electromagnetic waves in a medium.

   From Maxwell's equations: c = 1/sqrt(mu_0*epsilon_0) in vacuum
   In a medium: v = 1/sqrt(mu*epsilon)

   Args:
       permeability: Permeability of the medium (H/m)
       permittivity: Permittivity of the medium (F/m)

   Returns:
       float: Speed of electromagnetic waves in the medium (m/s)

   Raises:
       ValueError: If permeability or permittivity is non-positive

   Example:
       >>> abs(electromagnetic_wave_speed() - 2.998e8) < 1e6
       True
       >>> speed = electromagnetic_wave_speed(
       ...     VACUUM_PERMEABILITY, 2*VACUUM_PERMITTIVITY
       ... )
       >>> abs(speed - 2.12e8) < 1e7
       True


.. py:function:: energy_density_electromagnetic(electric_field: float, magnetic_field: float, permittivity: float = VACUUM_PERMITTIVITY, permeability: float = VACUUM_PERMEABILITY) -> float

   Calculate the energy density of an electromagnetic field.

   The energy density u = (1/2)*(epsilon_0*E^2 + B^2/mu_0) represents the
   electromagnetic energy stored per unit volume.

   Args:
       electric_field: Magnitude of electric field (V/m)
       magnetic_field: Magnitude of magnetic field (T)
       permittivity: Permittivity of the medium (F/m)
       permeability: Permeability of the medium (H/m)

   Returns:
       float: Energy density (J/m³)

   Raises:
       ValueError: If permittivity or permeability is non-positive

   Example:
       >>> abs(energy_density_electromagnetic(1000, 1e-3) - 0.398) < 0.001
       True
       >>> abs(energy_density_electromagnetic(0, 1.0) - 397887) < 1
       True
       >>> abs(energy_density_electromagnetic(377, 1e-6) - 1.0e-6) < 1e-6
       True


.. py:function:: faraday_law(electric_field_circulation: float, magnetic_flux_change_rate: float) -> bool

   Faraday's law of electromagnetic induction: curl(E) = -dB/dt

   In integral form: ∮E·dl = -dPhi_B/dt

   This law describes how a changing magnetic field induces an electric field.
   The induced electric field opposes the change in magnetic flux (Lenz's law).

   Args:
       electric_field_circulation: Line integral of E around closed loop (V)
       magnetic_flux_change_rate: Rate of change of magnetic flux (Wb/s or V)

   Returns:
       bool: True if Faraday's law is satisfied within numerical tolerance

   Example:
       >>> faraday_law(10.0, -10.0)
       True
       >>> faraday_law(-5.0, 5.0)
       True
       >>> faraday_law(0.0, 0.0)
       True
       >>> faraday_law(10.0, 10.0)
       False


.. py:function:: gauss_law_electric(electric_field_magnitude: float, surface_area: float, enclosed_charge: float, permittivity: float = VACUUM_PERMITTIVITY) -> bool

   Gauss's law for electricity: div(E) = rho/epsilon_0

   In integral form: ∮E·dA = Q_enclosed/epsilon_0

   This law states that the electric flux through any closed surface is
   proportional to the total electric charge enclosed within that surface.

   Args:
       electric_field_magnitude: Magnitude of electric field (V/m or N/C)
       surface_area: Area of the closed surface (m²)
       enclosed_charge: Total charge enclosed by the surface (C - coulombs)
       permittivity: Permittivity of the medium (F/m), defaults to vacuum

   Returns:
       bool: True if Gauss's law is satisfied within numerical tolerance

   Raises:
       ValueError: If surface_area is negative or permittivity is non-positive

   Example:
       >>> gauss_law_electric(1000, 1.0, 8.854e-9)
       True
       >>> gauss_law_electric(500, 2.0, 8.854e-9)
       True
       >>> gauss_law_electric(-100, 1.0, 8.854e-9)
       False


.. py:function:: gauss_law_magnetic(surface_area: float) -> bool

   Gauss's law for magnetism: div(B) = 0

   In integral form: ∮B·dA = 0

   This law states that there are no magnetic monopoles - the magnetic flux
   through any closed surface is always zero. Magnetic field lines always
   form closed loops or extend to infinity.

   Args:
       surface_area: Area of the closed surface (m²)

   Returns:
       bool: Always True for physically realistic magnetic fields,
             False if net flux is non-zero (indicating monopoles)

   Raises:
       ValueError: If surface_area is negative

   Example:
       >>> gauss_law_magnetic(2.0)
       True
       >>> gauss_law_magnetic(0.0)
       True
       >>> gauss_law_magnetic(5.0)
       True


.. py:function:: poynting_vector_magnitude(electric_field: float, magnetic_field: float, permeability: float = VACUUM_PERMEABILITY) -> float

   Calculate the magnitude of the Poynting vector (electromagnetic power flow).

   The Poynting vector S = (1/mu_0) * E x B represents the directional energy
   flux density of an electromagnetic field (power per unit area).

   Args:
       electric_field: Magnitude of electric field (V/m)
       magnetic_field: Magnitude of magnetic field (T)
       permeability: Permeability of the medium (H/m)

   Returns:
       float: Magnitude of Poynting vector (W/m²)

   Raises:
       ValueError: If permeability is non-positive

   Example:
       >>> abs(poynting_vector_magnitude(1000, 1e-6) - 795.8) < 1.0
       True
       >>> abs(poynting_vector_magnitude(377, 1.0) - 3.0e8) < 1e6
       True
       >>> poynting_vector_magnitude(0, 1.0)
       0.0


.. py:data:: SPEED_OF_LIGHT
   :value: 299792458


.. py:data:: VACUUM_PERMEABILITY
   :value: 1.2566370614359173e-06


.. py:data:: VACUUM_PERMITTIVITY
   :value: 8.8541878128e-12


.. py:data:: c