Documentation: electricity (circuits) (#959)

* Fix documentation

* Fix issues

* Fix issue

symplyphysics/laws/electricity/circuits/couplers/attenuation_coefficient_of_three_link_microwave_attenuator.py

@@ -1,42 +1,54 @@
+"""
+Attenuation of three link microwave attenuator
+==============================================
+
+Microwave attenuators are used to attenuate the microwave signal. For a three-link
+T-type attenuator or a π-type attenuator, the signal attenuation coefficient is
+calculated from the ratio of resistances of the resistors.
+
+..
+    TODO: find link
+    TODO: fix file name
+"""
+
 from sympy import Eq, solve, exp, acosh
 from symplyphysics import (
-    units,
     Quantity,
-    Symbol,
-    print_expression,
     validate_input,
     validate_output,
-    dimensionless,
     convert_to_float,
+    symbols,
+    clone_as_symbol,
 )
 
-# Description
-## Microwave attenuators are used to attenuate the microwave signal. For a three-link T-type attenuator or a π-type
-## attenuator, the signal attenuation coefficient is calculated from the resistor resistance ratio.
-
-## Law is: N = exp(arcosh(1 + R1 / R2)), where
-## N - attenuation coefficient of attenuator,
-## R1 - resistance of the first resistor,
-## R2 - resistance of the second resistor,
-## arcosh - this is area hyperbolic cosine (https://en.wikipedia.org/wiki/Hyperbolic_functions).
-
-attenuation_coefficient = Symbol("attenuation_coefficient", dimensionless)
+attenuation = symbols.attenuation
+"""
+:symbols:`attenuation` of the attenuator.
+"""
 
-first_resistance = Symbol("first_resistance", units.impedance)
-second_resistance = Symbol("second_resistance", units.impedance)
+first_resistance = clone_as_symbol(symbols.electrical_resistance, subscript="1")
+"""
+:symbols:`electrical_resistance` of the first section.
+"""
 
-law = Eq(attenuation_coefficient, exp(acosh(1 + first_resistance / second_resistance)))
+second_resistance = clone_as_symbol(symbols.electrical_resistance, subscript="2")
+"""
+:symbols:`electrical_resistance` of the second section.
+"""
 
+law = Eq(attenuation, exp(acosh(1 + first_resistance / second_resistance)))
+"""
+:laws:symbol::
 
-def print_law() -> str:
-    return print_expression(law)
+:laws:latex::
+"""
 
 
 @validate_input(first_resistance_=first_resistance, second_resistance_=second_resistance)
-@validate_output(attenuation_coefficient)
+@validate_output(attenuation)
 def calculate_attenuation_coefficient(first_resistance_: Quantity,
     second_resistance_: Quantity) -> float:
-    result_expr = solve(law, attenuation_coefficient, dict=True)[0][attenuation_coefficient]
+    result_expr = solve(law, attenuation, dict=True)[0][attenuation]
     result_expr = result_expr.subs({
         first_resistance: first_resistance_,
         second_resistance: second_resistance_,

symplyphysics/laws/electricity/circuits/couplers/conductivity_for_rectangular_loop_coupler.py

@@ -1,63 +1,100 @@
+"""
+Admittance of rectangular loop coupler
+======================================
+
+The rectangular loop coupler consists of four sections. The admittance of each section
+can be calculated by calculating the admittance of the transmission line to which the
+coupler is connected and the power ratio at the outputs.
+
+..
+    TODO: find link
+    TODO: rename file
+"""
+
 from sympy import Eq, solve, Matrix, sqrt
 from symplyphysics import (
     units,
     Quantity,
-    Symbol,
-    print_expression,
+    SymbolNew,
     validate_input,
     validate_output,
     dimensionless,
+    symbols,
+    clone_as_symbol,
 )
 
-## Description
-## The rectangular loop coupler consists of four sections. The conductivity of each section can be calculated by calculating
-## the conductivity of the transmission line to which the coupler is connected and the power ratio at the outputs.
+first_admittance = clone_as_symbol(symbols.admittance, subscript="1")
+"""
+:symbols:`admittance` of the first section.
+"""
+
+second_admittance = clone_as_symbol(symbols.admittance, subscript="2")
+"""
+:symbols:`admittance` of the second section.
+"""
+
+third_admittance = clone_as_symbol(symbols.admittance, subscript="3")
+"""
+:symbols:`admittance` of the third section.
+"""
 
-## Law is: Matrix([Y1, Y2, Y3, Y4]) = Matrix([Y0 / sqrt(k), Y0 * sqrt((k + 1) / k), Y0 * sqrt((k + 1) / k), Y0 / sqrt(k)]), where
-## Y1 - first conductivity,
-## Y2 - second conductivity,
-## Y3 - third conductivity,
-## Y4 - fourth conductivity,
-## Y0 - transmission line conductivity,
-## k - ratio coefficient of the power at the outputs of the coupler.
+fourth_admittance = clone_as_symbol(symbols.admittance, subscript="4")
+"""
+:symbols:`admittance` of the fourth section.
+"""
 
-first_conductivity = Symbol("first_conductivity", units.conductance)
-second_conductivity = Symbol("second_conductivity", units.conductance)
-third_conductivity = Symbol("third_conductivity", units.conductance)
-fourth_conductivity = Symbol("fourth_conductivity", units.conductance)
+transmission_line_admittance = clone_as_symbol(symbols.admittance, subscript="0")
+"""
+:symbols:`admittance` of the transmission line.
+"""
 
-transmission_line_conductivity = Symbol("transmission_line_conductivity", units.conductance)
-ratio_of_power = Symbol("ratio_of_power", dimensionless)
+power_ratio = SymbolNew("k", dimensionless)
+"""
+Ratio of the power at the outputs of the coupler.
+"""
 
 law = Eq(
-    Matrix([first_conductivity, second_conductivity, third_conductivity, fourth_conductivity]),
-    Matrix([
-    transmission_line_conductivity / sqrt(ratio_of_power), transmission_line_conductivity * sqrt(
-    (ratio_of_power + 1) / ratio_of_power), transmission_line_conductivity * sqrt(
-    (ratio_of_power + 1) / ratio_of_power), transmission_line_conductivity / sqrt(ratio_of_power)
+    Matrix([first_admittance, second_admittance, third_admittance, fourth_admittance]),
+    transmission_line_admittance * Matrix([
+        1 / sqrt(power_ratio),
+        sqrt((power_ratio + 1) / power_ratio),
+        sqrt((power_ratio + 1) / power_ratio),
+        1 / sqrt(power_ratio),
     ]))
+r"""
+..
+    Code printers don't work with matrices yet.
 
+:code:`[Y_1, Y_2, Y_3, Y_4] = Y_0 * [1 / sqrt(k), sqrt((k + 1) / k), sqrt((k + 1) / k), 1 / sqrt(k)]`
 
-def print_law() -> str:
-    return print_expression(law)
+Latex:
+    .. math::
+        \begin{pmatrix} Y_1 \\ Y_2 \\ Y_3 \\ Y_4 \end{pmatrix}
+        = Y_0 \begin{pmatrix}
+            \frac{1}{\sqrt{k}} \\
+            \sqrt{\frac{k + 1}{k}} \\
+            \sqrt{\frac{k + 1}{k}} \\
+            \frac{1}{\sqrt{k}} \\
+        \end{pmatrix}
+"""
 
 
-@validate_input(transmission_line_conductivity_=transmission_line_conductivity,
-    ratio_of_power_=ratio_of_power)
+@validate_input(transmission_line_admittance_=transmission_line_admittance,
+    ratio_of_power_=power_ratio)
 @validate_output(units.conductance)
 def calculate_conductivities(
-        transmission_line_conductivity_: Quantity,
+        transmission_line_admittance_: Quantity,
         ratio_of_power_: float) -> tuple[Quantity, Quantity, Quantity, Quantity]:
     result = solve(law,
-        [first_conductivity, second_conductivity, third_conductivity, fourth_conductivity],
+        [first_admittance, second_admittance, third_admittance, fourth_admittance],
         dict=True)[0]
-    result_y1 = result[first_conductivity]
-    result_y2 = result[second_conductivity]
-    result_y3 = result[third_conductivity]
-    result_y4 = result[fourth_conductivity]
+    result_y1 = result[first_admittance]
+    result_y2 = result[second_admittance]
+    result_y3 = result[third_admittance]
+    result_y4 = result[fourth_admittance]
     substitutions = {
-        transmission_line_conductivity: transmission_line_conductivity_,
-        ratio_of_power: ratio_of_power_,
+        transmission_line_admittance: transmission_line_admittance_,
+        power_ratio: ratio_of_power_,
     }
     result_y1 = Quantity(result_y1.subs(substitutions))
     result_y2 = Quantity(result_y2.subs(substitutions))

symplyphysics/laws/electricity/circuits/couplers/full_gain_of_transistor_amplifier.py

@@ -1,36 +1,61 @@
+"""
+Total gain of transistor amplifier
+==================================
+
+The total gain of a transistor amplifier depends on the gain of the input and output
+matching circuits and the transistor gain.
+
+..
+    TODO: find link
+"""
+
 from sympy import Eq, solve
-from symplyphysics import (Symbol, validate_input, validate_output, dimensionless, convert_to_float)
+from symplyphysics import (
+    validate_input,
+    validate_output,
+    convert_to_float,
+    symbols,
+    clone_as_symbol,
+)
+
+total_gain = clone_as_symbol(symbols.circuit_gain)
+"""
+Total gain of the transistor amplifier. See :symbols:`circuit_gain`.
+"""
 
-# Description
-## When calculating the total gain of a transistor amplifier, it is also worth taking into account
-## the gain coefficients of the input and output matching circuits.
+input_circuit_gain = clone_as_symbol(symbols.circuit_gain, display_symbol="gain_i", display_latex="\\text{gain}_\\text{i}")
+"""
+Input matching :symbols:`circuit_gain`.
+"""
 
-## Law is: G = G1 * G2 * G3, where
-## G - full gain of the transistor amplifier,
-## G1 - gain of the input matching circuit,
-## G2 - transistor gain,
-## G3 - gain of the output matching circuit.
+transistor_gain = clone_as_symbol(symbols.circuit_gain, display_symbol="gain_t", display_latex="\\text{gain}_\\text{t}")
+"""
+Transistor gain. See :symbols:`circuit_gain`.
+"""
 
-full_gain = Symbol("full_gain", dimensionless)
+output_circuit_gain = clone_as_symbol(symbols.circuit_gain, display_symbol="gain_o", display_latex="\\text{gain}_\\text{o}")
+"""
+Output matching :symbols:`circuit_gain`.
+"""
 
-gain_of_input_matching_circuit = Symbol("gain_of_input_matching_circuit", dimensionless)
-transistor_gain = Symbol("transistor_gain", dimensionless)
-gain_of_output_matching_circuit = Symbol("gain_of_output_matching_circuit", dimensionless)
+law = Eq(total_gain, input_circuit_gain * transistor_gain * output_circuit_gain)
+"""
+:laws:symbol::
 
-law = Eq(full_gain,
-    gain_of_input_matching_circuit * transistor_gain * gain_of_output_matching_circuit)
+:laws:latex::
+"""
 
 
-@validate_input(gain_of_input_matching_circuit_=gain_of_input_matching_circuit,
+@validate_input(gain_of_input_matching_circuit_=input_circuit_gain,
     transistor_gain_=transistor_gain,
-    gain_of_output_matching_circuit_=gain_of_output_matching_circuit)
-@validate_output(full_gain)
+    gain_of_output_matching_circuit_=output_circuit_gain)
+@validate_output(total_gain)
 def calculate_full_gain(gain_of_input_matching_circuit_: float, transistor_gain_: float,
     gain_of_output_matching_circuit_: float) -> float:
-    result_expr = solve(law, full_gain, dict=True)[0][full_gain]
+    result_expr = solve(law, total_gain, dict=True)[0][total_gain]
     result_expr = result_expr.subs({
-        gain_of_input_matching_circuit: gain_of_input_matching_circuit_,
+        input_circuit_gain: gain_of_input_matching_circuit_,
         transistor_gain: transistor_gain_,
-        gain_of_output_matching_circuit: gain_of_output_matching_circuit_,
+        output_circuit_gain: gain_of_output_matching_circuit_,
     })
     return convert_to_float(result_expr)