Documentation: electricity

symplyphysics/laws/electricity/characteristic_resistance_of_medium.py

@@ -1,37 +1,50 @@
-from sympy import (
-    Eq,
-    solve,
-    pi,
-    sqrt,
-)
+"""
+Characteristic resistance of medium
+===================================
+
+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.
+
+..
+    TODO: find link
+"""
+
+from sympy import Eq, solve, pi, sqrt
 from symplyphysics import (
     units,
     Quantity,
-    Symbol,
     validate_input,
     validate_output,
-    dimensionless,
+    symbols,
 )
 
-# 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.
+resistance = symbols.electrical_resistance
+"""
+:symbols:`electrical_resistance` of the medium.
+"""
 
-# TODO find link
+relative_permittivity = symbols.relative_permittivity
+"""
+:symbols:`relative_permittivity` of the medium.
+"""
 
-resistance = Symbol("resistance", units.impedance)
+relative_permeability = symbols.relative_permeability
+"""
+:symbols:`relative_permeability` of the medium.
+"""
 
-relative_permittivity = Symbol("relative_permittivity", dimensionless)
-relative_permeability = Symbol("relative_permeability", dimensionless)
+impedance_constant = Quantity(120 * pi * units.ohm, display_symbol="Z_0")
+"""
+Constant equal to :math:`120 \\Omega`.
+"""
 
-impedance_vacuum = Quantity(120 * pi * units.ohm)
+law = Eq(resistance, impedance_constant * 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,

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.
+# "coil_impedance_from_coil_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))
+assert expr_equals(lhs := abs(_circuit_impedance_derived), rhs := expand(law.rhs)), (lhs, 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)

symplyphysics/laws/electricity/circuits/input_impedance_of_thin_film_resistor.py

@@ -1,26 +1,45 @@
-from sympy import Eq, solve, I, pi
-from symplyphysics import (units, Quantity, Symbol, validate_input, validate_output)
+"""
+Input impedance of thin film resistor
+=====================================
+
+Thin-film resistors in integrated design are used in microwave circuits. The input
+impedance of a thin-film resistor depends on its resistance and capacitance, as well as
+on the frequency.
 
-# Description
-## Thin-film resistors in integrated design are used in microwave circuits. The input impedance of a thin-film resistor
-## depends on its resistance and capacitance, as well as on the frequency.
+..
+    TODO: find link
+    NOTE: replace `2 * pi * f` with `omega`
+"""
 
-## Law is: Zin = R / (1 + I * 2 * pi * f * R * C / 3), where
-## Zin - input impedance of a thin-film resistor,
-## R - resistance,
-## I - imaginary unit,
-## f - frequency,
-## C - capacitance.
+from sympy import Eq, solve, I, pi
+from symplyphysics import Quantity, validate_input, validate_output, symbols
 
-# TODO find link
+input_impedance = symbols.electrical_impedance
+"""
+Input :symbols:`electrical_impedance` of the resistor.
+"""
 
-input_impedance = Symbol("input_impedance", units.impedance)
+resistance = symbols.electrical_resistance
+"""
+:symbols:`electrical_resistance` of the film.
+"""
 
-resistance = Symbol("resistance", units.impedance)
-frequency = Symbol("frequency", units.frequency)
-capacitance = Symbol("capacitance", units.capacitance)
+frequency = symbols.temporal_frequency
+"""
+:symbols:`temporal_frequency` of the current.
+"""
+
+capacitance = symbols.capacitance
+"""
+:symbols:`capacitance` of the film.
+"""
 
 law = Eq(input_impedance, resistance / (1 + I * 2 * pi * frequency * resistance * capacitance / 3))
+"""
+:laws:symbol::
+
+:laws:latex::
+"""
 
 
 @validate_input(