rtds-circuit-analysis 0.0.1__tar.gz

rtds_circuit_analysis-0.0.1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Guilherme Natan Ferro Braga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

rtds_circuit_analysis-0.0.1/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: rtds-circuit-analysis
+Version: 0.0.1
+Summary: Solve electrical circuits
+Author-email: Guilherme Natan <guilherme.natan.braga@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Guilherme-Natan/rtds-circuit-analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sympy>=1.13.3
+Requires-Dist: networkx>=3.4.2
+Requires-Dist: scipy>=1.16.3
+Requires-Dist: pytest>=8.3.5
+Dynamic: license-file
+
+# RTDS Circuit Analysis
+
+RTDS Circuit Analysis is a Python software for solving electrical circuits, when given their [netlist](#netlist).
+
+## Installation
+
+If you plan on using the [command line interface](#command-line-interface) for this software, you can use
+[pipx](https://github.com/pypa/pipx) for this:
+
+<!-- TODO: Check if the names for the pipx and pip packages are correct -->
+```bash
+pipx install rtds-circuit-analysis
+```
+
+If you want to use the [library](#library), however, you might prefer using [pip](https://pip.pypa.io/en/stable/) for the installation:
+```bash
+pip install rtds-circuit-analysis
+```
+
+## Netlist
+
+Before actually [using](#usage) this program, you will need to write the circuit you want to analise as a *netlist*.
+This software uses a netlist style similar to SPICE programs, where each line corresponds to each component in the
+circuit. They will be formatted like `Vin in 0 V`, where:
+- The the first letter in the first word, `V` is the component type (V for voltage source, R for resistors, etc), and
+  together with the rest, `Vin`, make up the component name.
+- The second and third words are the nodes the component is connected to. Their names are arbitrary, except for the node
+  0, which will **always** be ground. It is also **always** necessary.
+- The final word will be the value for the circuit. It can be a literal (such as in this case, `V`), a numeric value
+  (like `10k`), or a combination of both (like `10V`).
+
+<!-- TODO: Link to the sphinx section about netlists here -->
+
+For example, here is a basic RLC circuit...
+
+![rlc_circuit](./docs/_static/rlc_circuit.png)
+
+... and its netlist representation:
+```
+V1 1 0 10
+R1 1 2 1k
+L1 2 3 100m
+C1 3 0 10u
+```
+
+## Usage
+
+### Command Line Interface
+
+The basic usage for the CLI software is in the form:
+
+```bash
+rtds-circuit-analysis netlist.cir
+```
+
+`netlist.cir` being the path for the file containing the [netlist](#netlist). This will print all the solutions for the
+circuit (node voltages, currents, states, etc). You can use flags to filter the output. For example, to show only the
+currents for each component, you can run:
+
+```bash
+rtds-circuit-analysis netlist.cir -i
+```
+
+You can filter it even more, by giving the components/node names to the flags as parameters. So, if you want the voltage
+and current for the resistor R1 only, you can run:
+
+```bash
+rtds-circuit-analysis netlist.cir -v R1 -i R1
+```
+
+<!-- TODO: Link the section about the cli in the sphinx docs here -->
+
+### Library
+
+To solve the circuit, you need to import the `Circuit` class, and pass the netlist as a parameter, creating a circuit
+object.
+
+```python
+from rtds_circuit_analysis import Circuit
+
+circuit = Circuit("netlist.cir")
+```
+
+This Circuit object will have all circuit solutions stored as attributes. So, for example, to find the voltage at node
+"2", you can use:
+
+```python
+circuit.node_voltages["2"]
+```
+
+You can also use the `print` methods to print the solutions for the circuit in a formatted manner, similar to the
+[CLI](#command-line-interface). For example, to print the voltages for the components R1 and R2, you can run:
+
+```python
+circuit.print_component_voltages("R1", "R2")
+```
+
+<!-- TODO: Link the section about the library in the sphinx docs here -->
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

rtds_circuit_analysis-0.0.1/README.md

@@ -0,0 +1,102 @@
+# RTDS Circuit Analysis
+
+RTDS Circuit Analysis is a Python software for solving electrical circuits, when given their [netlist](#netlist).
+
+## Installation
+
+If you plan on using the [command line interface](#command-line-interface) for this software, you can use
+[pipx](https://github.com/pypa/pipx) for this:
+
+<!-- TODO: Check if the names for the pipx and pip packages are correct -->
+```bash
+pipx install rtds-circuit-analysis
+```
+
+If you want to use the [library](#library), however, you might prefer using [pip](https://pip.pypa.io/en/stable/) for the installation:
+```bash
+pip install rtds-circuit-analysis
+```
+
+## Netlist
+
+Before actually [using](#usage) this program, you will need to write the circuit you want to analise as a *netlist*.
+This software uses a netlist style similar to SPICE programs, where each line corresponds to each component in the
+circuit. They will be formatted like `Vin in 0 V`, where:
+- The the first letter in the first word, `V` is the component type (V for voltage source, R for resistors, etc), and
+  together with the rest, `Vin`, make up the component name.
+- The second and third words are the nodes the component is connected to. Their names are arbitrary, except for the node
+  0, which will **always** be ground. It is also **always** necessary.
+- The final word will be the value for the circuit. It can be a literal (such as in this case, `V`), a numeric value
+  (like `10k`), or a combination of both (like `10V`).
+
+<!-- TODO: Link to the sphinx section about netlists here -->
+
+For example, here is a basic RLC circuit...
+
+![rlc_circuit](./docs/_static/rlc_circuit.png)
+
+... and its netlist representation:
+```
+V1 1 0 10
+R1 1 2 1k
+L1 2 3 100m
+C1 3 0 10u
+```
+
+## Usage
+
+### Command Line Interface
+
+The basic usage for the CLI software is in the form:
+
+```bash
+rtds-circuit-analysis netlist.cir
+```
+
+`netlist.cir` being the path for the file containing the [netlist](#netlist). This will print all the solutions for the
+circuit (node voltages, currents, states, etc). You can use flags to filter the output. For example, to show only the
+currents for each component, you can run:
+
+```bash
+rtds-circuit-analysis netlist.cir -i
+```
+
+You can filter it even more, by giving the components/node names to the flags as parameters. So, if you want the voltage
+and current for the resistor R1 only, you can run:
+
+```bash
+rtds-circuit-analysis netlist.cir -v R1 -i R1
+```
+
+<!-- TODO: Link the section about the cli in the sphinx docs here -->
+
+### Library
+
+To solve the circuit, you need to import the `Circuit` class, and pass the netlist as a parameter, creating a circuit
+object.
+
+```python
+from rtds_circuit_analysis import Circuit
+
+circuit = Circuit("netlist.cir")
+```
+
+This Circuit object will have all circuit solutions stored as attributes. So, for example, to find the voltage at node
+"2", you can use:
+
+```python
+circuit.node_voltages["2"]
+```
+
+You can also use the `print` methods to print the solutions for the circuit in a formatted manner, similar to the
+[CLI](#command-line-interface). For example, to print the voltages for the components R1 and R2, you can run:
+
+```python
+circuit.print_component_voltages("R1", "R2")
+```
+
+<!-- TODO: Link the section about the library in the sphinx docs here -->
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

rtds_circuit_analysis-0.0.1/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools >= 77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rtds-circuit-analysis"
+version = "0.0.1"
+authors = [
+  { name="Guilherme Natan", email="guilherme.natan.braga@gmail.com" },
+]
+description = "Solve electrical circuits"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = ["sympy>=1.13.3", "networkx>=3.4.2", "scipy>=1.16.3" , "pytest>=8.3.5"]
+license = "MIT"
+license-files = ["LICENSE"]
+
+[project.scripts]
+rtds-circuit-analysis = "rtds_cli.app:app"
+
+[project.urls]
+Homepage = "https://github.com/Guilherme-Natan/rtds-circuit-analysis"

rtds_circuit_analysis-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rtds_circuit_analysis-0.0.1/src/rtds_circuit_analysis/__init__.py

@@ -0,0 +1 @@
+from .circuit import Circuit

rtds_circuit_analysis-0.0.1/src/rtds_circuit_analysis/circuit.py

@@ -0,0 +1,137 @@
+"""Module that contains the circuit class"""
+
+import os
+
+from rtds_circuit_analysis.diference_equations import differential_to_difference
+from rtds_circuit_analysis.format_output import format_output
+from rtds_circuit_analysis.parse_data import parse_data
+from rtds_circuit_analysis.parse_netlist import get_lines, parse_components
+from rtds_circuit_analysis.solve_circuit import solve_circuit
+
+
+class Circuit:
+    """Class that represents a circuit and all its data."""
+
+    def __init__(self, circuit_data: str, time_step: str | None = None):
+        if os.path.exists(circuit_data):
+            circuit_data = get_lines(circuit_data)
+        else:
+            circuit_data = circuit_data.strip().split("\n")
+
+        self.components, possible_time_step = parse_components(circuit_data)
+        if possible_time_step:
+            time_step = possible_time_step
+
+        parse_data(self.components)
+
+        (
+            self.components,
+            self.currents,
+            self.component_voltages,
+            self.node_voltages,
+            self.states,
+        ) = solve_circuit(self.components)
+
+        if self.states:
+            self.forward, self.backward, self.trapezoidal = differential_to_difference(self.states, time_step)
+        else:
+            self.forward = self.backward = self.trapezoidal = None
+
+    def _formatted_components(self):
+        return f'*** Components for the circuit ***\n{"\n".join(str(component) for component in self.components)}\n'
+
+    def _formatted_currents(self, components=None):
+        return f"*** Currents ***\n{format_output(self.currents, components)}"
+
+    def _formatted_component_voltages(self, components=None):
+        return f"*** Voltages (components) ***\n{format_output(self.component_voltages, components)}"
+
+    def _formatted_node_voltages(self, nodes=None):
+        return f"*** Voltages (nodes) ***\n{format_output(self.node_voltages, nodes)}"
+
+    def _formatted_states(self, components=None):
+        return f"*** State equations (continuous) ***\
+        \n{format_output(self.states, components, is_state=True, lhs_is_derivative=True)}"
+
+    def _formatted_forward(self, components=None):
+        return f"*** State equations (forward) ***\
+        \n{format_output(self.forward, components, is_state=True, is_discrete=True)}"
+
+    def _formatted_backward(self, components=None):
+        return f"*** State equations (backward) ***\
+        \n{format_output(self.backward, components, is_state=True, is_discrete=True)}"
+
+    def _formatted_trapezoidal(self, components=None):
+        return f"*** State equations (trapezoidal) ***\
+        \n{format_output(self.trapezoidal, components, is_state=True, is_discrete=True)}"
+
+    def print_components(self):
+        """Print all components for the circuit"""
+        print(self._formatted_components)
+
+    def print_currents(self, *components):
+        """Prints the current for the given components (excluding inductors and current sources, which are obvious). If
+        no components are given, prints the currents for *every* component."""
+        print(self._formatted_currents(components))
+
+    def print_component_voltages(self, *components):
+        """Prints the voltage for the given components (excluding capacitors and voltage sources, which are obvious). If
+        no components are given, prints the voltages for *every* component."""
+        print(self._formatted_component_voltages(components))
+
+    def print_node_voltages(self, *nodes):
+        """Prints the voltage for each node. If no nodes are given, prints the voltages for every node."""
+        print(self._formatted_node_voltages(nodes))
+
+    def print_states(self, *components):
+        """Prints the state equations for the system (continuous). If no components are given,"""
+        print(self._formatted_states(components))
+
+    def print_forward(self, *components):
+        """Prints the state equations for the system (forward)."""
+        print(self._formatted_forward(components))
+
+    def print_backward(self, *components):
+        """Prints the state equations for the system (backward)."""
+        print(self._formatted_backward(components))
+
+    def print_trapezoidal(self, *components):
+        """Prints the state equations for the system (trapezoidal)."""
+        print(self._formatted_trapezoidal(components))
+
+    def print_all(self):
+        """Prints all the info related to the `circuit` object."""
+        self.print_currents()
+        self.print_component_voltages()
+        self.print_node_voltages()
+        if self.states:
+            self.print_states()
+            self.print_forward()
+            self.print_backward()
+            self.print_trapezoidal()
+        else:
+            print("*** This circuit is stateless ***")
+            print("")
+
+    def __str__(self):
+        return f"""{self._formatted_components()}
+{self._formatted_currents()}
+{self._formatted_component_voltages()}
+{self._formatted_node_voltages()}
+{self._formatted_states()}
+{self._formatted_forward()}
+{self._formatted_backward()}
+{self._formatted_trapezoidal()}"""
+
+    def __repr__(self):
+        return f"""Circuit(
+components={str(self.components)},
+node_voltages={self.node_voltages},
+currents={self.currents},
+component_voltages={self.component_voltages},
+states={self.states}
+forward={self.forward}
+backward={self.backward}
+trapezoidal={self.trapezoidal}
+)
+"""

rtds_circuit_analysis-0.0.1/src/rtds_circuit_analysis/diference_equations.py

@@ -0,0 +1,224 @@
+"""Functions related to converting differential equations to difference equations"""
+
+from dataclasses import dataclass
+from typing import Callable
+
+import sympy as sp
+
+
+@dataclass
+class DifferenceEquations:
+    """Class to store the difference equations for the circuit, in their implicit form."""
+
+    forward: list[sp.Eq]
+    backward: list[sp.Eq]
+    trapezoidal: list[sp.Eq]
+
+
+@dataclass
+class DifferenceSolution:
+    """The solutions for each difference method."""
+
+    forward: dict[str, sp.Eq]
+    backward: dict[str, sp.Eq]
+    trapezoidal: dict[str, sp.Eq]
+
+
+@dataclass
+class Symbols:
+    """Symbols that correspond to values that vary with time within a circuit. In their differential form, and in their
+    equivalent difference form.
+    """
+
+    continuous: list[sp.Expr]
+    discrete_equivalent: list[sp.Expr]
+
+
+def forward(continuous_symbols: sp.Symbol) -> list[sp.Symbol]:
+    """Transform a symbol in continuous form to its difference form, using the forward method.
+
+    Args:
+        continuous_symbols (sp.Symbol): Symbol in continuous form.
+
+    Returns:
+        list[sp.Symbol]: Symbol in difference form.
+    """
+
+    return sp.Symbol(str(continuous_symbols) + "_{n-1}")
+
+
+def backward(continuous_symbols: sp.Symbol) -> list[sp.Symbol]:
+    """Transform a symbol in continuous form to its difference form, using the backward method.
+
+    Args:
+        continuous_symbols (sp.Symbol): Symbol in continuous form.
+
+    Returns:
+        list[sp.Symbol]: Symbol in difference form.
+    """
+    return sp.Symbol(str(continuous_symbols) + "_{n}")
+
+
+def trapezoidal(continuous_symbols: sp.Symbol) -> list[sp.Expr]:
+    """Transform a symbol in continuous form to its difference form, using the trapezoidal method.
+
+    Args:
+        continuous_symbols (sp.Symbol): Symbol in continuous form.
+
+    Returns:
+        list[sp.Expr]: Expression in difference form.
+    """
+    return (forward(continuous_symbols) + backward(continuous_symbols)) / 2
+
+
+def convert_to(
+    discrete_method: Callable, variable: str, continuous_expression: sp.Expr, time_step: str | None
+) -> sp.Eq:
+    """Convert a state equation in differential form, to its respective difference form.
+
+    Args:
+        discrete_method (Callable): The method to use for the transform.
+        variable (str): The variable related to the component's equation, in differential form.
+        continuous_expression (sp.Expr): The variable's expression, in continuous form, related to the "right hand side"
+        of the state equation.
+        time_step (str | None): The time step for the circuit. If it is None, the expressions will receive the
+        time step as a "Ts" sympy symbol.
+
+    Returns:
+        sp.Eq: The state equation in difference form.
+    """
+    # Get the symbols for the expression
+    symbols = Symbols(list(continuous_expression.free_symbols), [])
+
+    # Keep only the symbols that vary with time (voltages and currents, symbols that begin with V or I)
+    symbols_filtered = []
+    for symbol in symbols.continuous:
+        if str(symbol)[0] in ("V", "I"):
+            symbols_filtered.append(symbol)
+    symbols.continuous = symbols_filtered
+
+    # Finds the equivalent form of each continuous symbol for the discrete method used
+    for symbol in symbols.continuous:
+        symbols.discrete_equivalent.append(discrete_method(symbol))
+
+    # Substitutes the discrete symbols in the continuous expression
+    discrete_expression = continuous_expression
+    for symbol_continuous, symbol_discrete in zip(symbols.continuous, symbols.discrete_equivalent):
+        discrete_expression = discrete_expression.subs(symbol_continuous, symbol_discrete)
+
+    # Returns the equation
+    new_value, old_value = sp.Symbol(variable + "_{n}"), sp.Symbol(variable + "_{n-1}")
+    if not time_step:
+        time_step = sp.Symbol("Ts")
+    else:
+        time_step = sp.Rational(time_step)
+    return sp.Eq(new_value, old_value + time_step * discrete_expression)
+
+
+def keys_to_string(dictionary: dict) -> dict:
+    """Transforms every key in a dictionary to a string.
+
+    Args:
+        dictionary (dict): Dictionary to transform
+
+    Returns:
+        dict: Dictionary, with its keys as strings.
+    """
+    return {str(k): v for k, v in dictionary.items()}
+
+
+def variable_to_component(solutions: dict[str, sp.Expr]) -> dict[str, sp.Expr]:
+    """Extracts the name of the capacitor/inductor from their voltage/current literal values. This is done by simply
+    removing the first letter (V or I), and the last four character (_{n}) from the string.
+
+    Args:
+        solutions (dict[str, sp.Expr]): A dictionary, where the keys are the components state variables.
+
+    Returns:
+        dict[str, sp.Expr]: A dictionary, where the keys are the component names.
+    """
+    # By removing the first and 4 last letters from the variable name, the component is extracted
+    return {variable[1:-4]: expression for variable, expression in solutions.items()}
+
+
+def symbol_to_component(solutions: dict[sp.Symbol, sp.Expr]) -> dict[str, sp.Expr]:
+    """Transforms the keys for the solutions dictionary from sympy symbols to the component names they relate to.
+
+    Args:
+        solutions (dict[sp.Symbol, sp.Expr]): The dictionary, where its keys are sympy symbols.
+
+    Returns:
+        dict[str, sp.Expr]: Dictionary, with keys related to the component names.
+    """
+    solutions = keys_to_string(solutions)
+    return variable_to_component(solutions)
+
+
+def convert_explicit(
+    discrete_method: Callable,
+    states_continuous: list[sp.Expr],
+    to_solve_for: list[sp.Expr],
+    time_step: str | None,
+) -> dict[str, sp.Expr]:
+    """Convert the state equations in continuous form into their (explicit) discrete form.
+
+    Args:
+        discrete_method (Callable): The method to use for the transform.
+        states_continuous (list[sp.Expr]): The state equations for the circuit, in continuous form.
+        to_solve_for (list[sp.Expr]):
+        time_step (str | None): The time step for the circuit. If it is None, the expressions will receive the
+        time step as a "Ts" sympy symbol.
+
+    Returns:
+        dict[str, sp.Expr]: The state equations for the chosen method
+    """
+    # Get the diference equations (implicit form)
+    difference_equations = []
+    for variable, state_expression in states_continuous.items():
+        difference_equations.append(convert_to(discrete_method, variable, state_expression, time_step))
+
+    # Turn them into their explicit form
+    solutions = sp.solve(difference_equations, to_solve_for)
+
+    # Turn the keys in the solutions dictionaries
+    return symbol_to_component(solutions)
+
+
+def differential_to_difference(
+    states_continuous: list[sp.Expr], time_step: str | None = None
+) -> tuple[dict[str, sp.Expr], dict[str, sp.Expr], dict[str, sp.Expr]]:
+    """Transform the state equations in continuous form in the circuit, into their difference form, for the forward,
+    backward and trapezoidal methods.
+
+    Args:
+        states_continuous (list[sp.Expr]): List of differential equations.
+        time_step (str | None): The time step for the circuit. If it is None, the expressions will receive the
+        time step as a "Ts" sympy symbol.
+
+
+    Returns:
+        tuple[dict[str, sp.Expr], dict[str, sp.Expr], dict[str, sp.Expr]]: State equations in differential form,
+        for various methods.
+    """
+    # Turn the keys from the component name to the variable related to this component.
+    states_continuous_variables = {}
+    for component, expression in states_continuous.items():
+        match component[0]:
+            case "C":
+                component = "V" + component
+            case "L":
+                component = "I" + component
+        states_continuous_variables[component] = expression
+    states_continuous = states_continuous_variables
+
+    # Extract the symbols
+    to_solve_for = []
+    for variable in states_continuous:
+        to_solve_for.append(sp.Symbol(variable + "_{n}"))
+
+    # Get the difference equations for each method
+    forward_solutions = convert_explicit(forward, states_continuous, to_solve_for, time_step)
+    backward_solutions = convert_explicit(backward, states_continuous, to_solve_for, time_step)
+    trapezoidal_solutions = convert_explicit(trapezoidal, states_continuous, to_solve_for, time_step)
+
+    return forward_solutions, backward_solutions, trapezoidal_solutions