Documentation: electricity

symplyphysics/laws/electricity/characteristic_resistance_of_medium.py

@@ -1,44 +1,64 @@
-from sympy import (
-    Eq,
-    solve,
-    pi,
-    sqrt,
-)
+"""
+Wave impedance from permeability and permittivity
+=================================================
+
+The impedance of a wave is a value determined by the ratio of the transverse component
+of the electric field to the transverse component of the magnetic field of a traveling
+wave.
+
+**Notation:**
+
+#. :quantity_notation:`vacuum_impedance`.
+
+**Conditions:**
+
+#. The dielectric medium is ideal, i.e. its conductivity :math:`sigma = 0`.
+
+**Links:**
+
+#. `Wikipedia, derivable from last formula in paragraph <https://en.wikipedia.org/wiki/Wave_impedance#Definition>`__.
+
+..
+    TODO: rename file
+"""
+
+from sympy import Eq, solve, sqrt
 from symplyphysics import (
-    units,
     Quantity,
-    Symbol,
     validate_input,
     validate_output,
-    dimensionless,
+    symbols,
+    quantities,
 )
 
-# Description
-## The characteristic resistance of a wave is a value determined by the ratio of the transverse component
-## of the electric field strength to the transverse component of the magnetic field strength of a traveling wave.
-
-## Law is: Z = 120 * pi * sqrt(mur / er), where
-## Z - characteristic resistance,
-## mur - relative permeability of the insulator material,
-## er - relative permittivity of insulating material.
-
-# TODO find link
+wave_impedance = symbols.wave_impedance
+"""
+:symbols:`wave_impedance`.
+"""
 
-resistance = Symbol("resistance", units.impedance)
+relative_permittivity = symbols.relative_permittivity
+"""
+:symbols:`relative_permittivity` of the medium.
+"""
 
-relative_permittivity = Symbol("relative_permittivity", dimensionless)
-relative_permeability = Symbol("relative_permeability", dimensionless)
+relative_permeability = symbols.relative_permeability
+"""
+:symbols:`relative_permeability` of the medium.
+"""
 
-impedance_vacuum = Quantity(120 * pi * units.ohm)
+law = Eq(wave_impedance, quantities.vacuum_impedance * sqrt(relative_permeability / relative_permittivity))
+"""
+:laws:symbol::
 
-law = Eq(resistance, impedance_vacuum * sqrt(relative_permeability / relative_permittivity))
+:laws:latex::
+"""
 
 
 @validate_input(relative_permittivity_=relative_permittivity,
     relative_permeability_=relative_permeability)
-@validate_output(resistance)
+@validate_output(wave_impedance)
 def calculate_resistance(relative_permittivity_: float, relative_permeability_: float) -> Quantity:
-    result_expr = solve(law, resistance, dict=True)[0][resistance]
+    result_expr = solve(law, wave_impedance, dict=True)[0][wave_impedance]
     result_expr = result_expr.subs({
         relative_permittivity: relative_permittivity_,
         relative_permeability: relative_permeability_,

symplyphysics/laws/electricity/circuits/capacitor_impedance_from_capacitive_reactance.py

@@ -1,34 +1,39 @@
-from sympy import (I, Eq, solve)
-from symplyphysics import (
-    units,
-    Quantity,
-    Symbol,
-    print_expression,
-    validate_input,
-    validate_output,
-)
+"""
+Capacitor impedance from capacitor reactance
+============================================
 
-# Description
-## While the serial resistance of ideal capacitor is zero, its impedance depends on its reactance.
-## Law: Zc = -j * Xc, where
-## Zc is capacitor impedance,
-## Xc is capacitive reactance.
+When the serial resistance of ideal capacitor is zero, its impedance depends on its reactance.
 
-capacitor_impedance = Symbol("capacitor_impedance", units.impedance)
-capacitive_reactance = Symbol("capacitive_reactance", units.impedance)
+..
+    TODO: find link
+"""
 
-law = Eq(capacitor_impedance, -I * capacitive_reactance)
+from sympy import I, Eq, solve
+from symplyphysics import Quantity, validate_input, validate_output, symbols
 
+impedance = symbols.electrical_impedance
+"""
+:symbols:`electrical_impedance` of a capacitor.
+"""
 
-def print_law() -> str:
-    return print_expression(law)
+reactance = symbols.electrical_reactance
+"""
+:symbols:`electrical_reactance` of a capacitor.
+"""
 
+law = Eq(impedance, -I * reactance)
+"""
+:laws:symbol::
 
-@validate_input(reactance_=capacitive_reactance)
-@validate_output(capacitor_impedance)
+:laws:latex::
+"""
+
+
+@validate_input(reactance_=reactance)
+@validate_output(impedance)
 def calculate_impedance(reactance_: Quantity) -> Quantity:
-    result_impedance_expr = solve(law, capacitor_impedance, dict=True)[0][capacitor_impedance]
+    result_impedance_expr = solve(law, impedance, dict=True)[0][impedance]
     result_expr = result_impedance_expr.subs({
-        capacitive_reactance: reactance_,
+        reactance: reactance_,
     })
     return Quantity(result_expr)

symplyphysics/laws/electricity/circuits/coil_impedance_from_inductive_reactance.py

@@ -1,35 +1,45 @@
+"""
+Coil impedance from inductive reactance
+=======================================
+
+The impedance of ideal coil depends on its inductive reactance. Having zero resistivity,
+the real part of coil impedance is zero.
+
+..
+    TODO: find link
+"""
+
 from sympy import (I, Eq, solve)
 from symplyphysics import (
-    units,
     Quantity,
-    Symbol,
-    print_expression,
     validate_input,
     validate_output,
+    symbols
 )
 
-# Description
-## The impedance of ideal coil depends on its inductive reactance. While having zero resistivity, the real part of
-## coil impedance is zero.
-## Law: Zl = j * Xl, where
-## Zl is coil impedance,
-## Xl is inductive reactance.
-
-coil_impedance = Symbol("coil_impedance", units.impedance)
-inductive_reactance = Symbol("inductive_reactance", units.impedance)
+impedance = symbols.electrical_impedance
+"""
+:symbols:`electrical_impedance` of a coil.
+"""
 
-law = Eq(coil_impedance, I * inductive_reactance)
+reactance = symbols.electrical_reactance
+"""
+:symbols:`electrical_reactance` of a coil.
+"""
 
+law = Eq(impedance, I * reactance)
+"""
+:laws:symbol::
 
-def print_law() -> str:
-    return print_expression(law)
+:laws:latex::
+"""
 
 
-@validate_input(reactance_=inductive_reactance)
-@validate_output(coil_impedance)
+@validate_input(reactance_=reactance)
+@validate_output(impedance)
 def calculate_impedance(reactance_: Quantity) -> Quantity:
-    result_impedance_expr = solve(law, coil_impedance, dict=True)[0][coil_impedance]
+    result_impedance_expr = solve(law, impedance, dict=True)[0][impedance]
     result_expr = result_impedance_expr.subs({
-        inductive_reactance: reactance_,
+        reactance: reactance_,
     })
     return Quantity(result_expr)

symplyphysics/laws/electricity/circuits/impedance_module_of_the_serial_resistor_coil_capacitor_circuit.py

@@ -1,72 +1,89 @@
+"""
+Impedance module of serial resistor-coil-capacitor circuit
+==========================================================
+
+Consider an electrical circuit consisting of a capacitor, coil, and resistor connected
+in series. Then you can find the impedance module of such a circuit.
+
+**Links:**
+
+#. `Wikipedia, derivable from first formula <https://en.wikipedia.org/wiki/Electrical_impedance#Resistance_vs_reactance>`__.
+"""
+
 from sympy import (Eq, solve, sqrt, Idx, expand)
-from symplyphysics import (units, Quantity, Symbol, validate_input, validate_output, global_index)
+from symplyphysics import (units, Quantity, SymbolNew, validate_input, validate_output, global_index, symbols, clone_as_symbol)
 from symplyphysics.core.expr_comparisons import expr_equals
-
 from symplyphysics.laws.electricity.circuits import capacitor_impedance_from_capacitive_reactance as capacitor_impedance_law
 from symplyphysics.laws.electricity.circuits import coil_impedance_from_inductive_reactance as coil_impedance_law
 from symplyphysics.laws.electricity.circuits import impedance_in_serial_connection as serial_law
 
-# Description
-## Consider an electrical circuit consisting of a capacitor, coil, and resistor connected in series.
-## Then you can find the impedance module of such a circuit.
+circuit_impedance_module = SymbolNew("abs(Z)", units.impedance, display_latex="|Z|")
+"""
+Absolute value of the circuit's :symbols:`electrical_impedance`.
+"""
 
-## Law is: |Z| = sqrt(R0^2 + (Xl - Xc)^2), where
-## Z - impedance of circuit,
-## |Z| - absolute value of Z,
-## R0 - resistance of resistor
-## Xl - inductive reactance,
-## Xc - capacitive reactance.
+resistor_resistance = clone_as_symbol(symbols.electrical_resistance, real=True)
+"""
+:symbols:`electrical_resistance` of the resistor.
+"""
 
-# Links: derivable from first formula <https://en.wikipedia.org/wiki/Electrical_impedance#Resistance_vs_reactance>
+capacitor_reactance = clone_as_symbol(symbols.electrical_reactance, subscript="\\text{C}", real=True)
+"""
+:symbols:`electrical_reactance` of the capacitor.
+"""
 
-circuit_resistance = Symbol("circuit_resistance", units.impedance, real=True)
+coil_reactance = clone_as_symbol(symbols.electrical_reactance, subscript="\\text{C}", real=True)
+"""
+:symbols:`electrical_reactance` of the coil.
+"""
 
-resistance_resistor = Symbol("resistance_resistor", units.impedance, real=True)
-capacitive_reactance = Symbol("capacitive_reactance", units.impedance, real=True)
-inductive_reactance = Symbol("inductive_reactance", units.impedance, real=True)
+law = Eq(circuit_impedance_module,
+    sqrt(resistor_resistance**2 + (coil_reactance - capacitor_reactance)**2))
+"""
+:laws:symbol::
 
-law = Eq(circuit_resistance,
-    sqrt(resistance_resistor**2 + (inductive_reactance - capacitive_reactance)**2))
+:laws:latex::
+"""
 
 # This law might be derived via "serial_impedance" law, "capacitor_impedance_from_capacitive_reactance" law,
 # "coil_impedance_from_inductive_reactance" law.
 
 _impedance_law_applied_1 = capacitor_impedance_law.law.subs({
-    capacitor_impedance_law.capacitive_reactance: capacitive_reactance,
+    capacitor_impedance_law.reactance: capacitor_reactance,
 })
 _capacitive_impedance_derived = solve(_impedance_law_applied_1,
-    capacitor_impedance_law.capacitor_impedance,
-    dict=True)[0][capacitor_impedance_law.capacitor_impedance]
+    capacitor_impedance_law.impedance,
+    dict=True)[0][capacitor_impedance_law.impedance]
 
 _impedance_law_applied_2 = coil_impedance_law.law.subs({
-    coil_impedance_law.inductive_reactance: inductive_reactance,
+    coil_impedance_law.reactance: coil_reactance,
 })
 _coil_impedance_derived = solve(_impedance_law_applied_2,
-    coil_impedance_law.coil_impedance,
-    dict=True)[0][coil_impedance_law.coil_impedance]
+    coil_impedance_law.impedance,
+    dict=True)[0][coil_impedance_law.impedance]
 
 _local_index = Idx("index_local", (1, 3))
 _serial_law_applied = serial_law.law.subs(global_index, _local_index)
 _serial_law_applied = _serial_law_applied.doit()
 _circuit_impedance_derived = solve(_serial_law_applied, serial_law.total_impedance,
     dict=True)[0][serial_law.total_impedance]
 for i, v in enumerate(
-    (resistance_resistor, _coil_impedance_derived, _capacitive_impedance_derived)):
+    (resistor_resistance, _coil_impedance_derived, _capacitive_impedance_derived)):
     _circuit_impedance_derived = _circuit_impedance_derived.subs(serial_law.impedance[i + 1], v)
 
 assert expr_equals(abs(_circuit_impedance_derived), expand(law.rhs))
 
 
-@validate_input(resistance_resistor_=resistance_resistor,
-    capacitive_reactance_=capacitive_reactance,
-    inductive_reactance_=inductive_reactance)
-@validate_output(circuit_resistance)
+@validate_input(resistance_resistor_=resistor_resistance,
+    capacitive_reactance_=capacitor_reactance,
+    coil_reactance_=coil_reactance)
+@validate_output(circuit_impedance_module)
 def calculate_circuit_impedance_module(resistance_resistor_: Quantity,
-    capacitive_reactance_: Quantity, inductive_reactance_: Quantity) -> Quantity:
-    result_expr = solve(law, circuit_resistance, dict=True)[0][circuit_resistance]
+    capacitive_reactance_: Quantity, coil_reactance_: Quantity) -> Quantity:
+    result_expr = solve(law, circuit_impedance_module, dict=True)[0][circuit_impedance_module]
     result_expr = result_expr.subs({
-        resistance_resistor: resistance_resistor_,
-        capacitive_reactance: capacitive_reactance_,
-        inductive_reactance: inductive_reactance_
+        resistor_resistance: resistance_resistor_,
+        capacitor_reactance: capacitive_reactance_,
+        coil_reactance: coil_reactance_
     })
     return Quantity(result_expr)