fixes from sarah's comments: update docstrings, add _ to private functions, remove mutable types from function argument, etc

Author: amzhao16

pygridsim/__init__.py

@@ -4,6 +4,6 @@
 
 __author__ = 'Angela Zhao'
 __email__ = '[email protected]'
-__version__ = '0.1.0.0'
+__version__ = '0.1.0.dev0'
 
 from pygridsim.core import PyGridSim as PyGridSim

pygridsim/__pycache__/__init__.cpython-312.pyc

@@ -1,15 +1,24 @@
 # -*- coding: utf-8 -*-
 from altdss import altdss
-from pygridsim.parameters import make_load_node, make_source_node, make_generator, make_pv
+from pygridsim.parameters import _make_load_node, _make_source_node, _make_generator, _make_pv
 from pygridsim.results import query_solution, export_results
-from pygridsim.lines import make_line
+from pygridsim.lines import _make_line
 
 """Main module."""
 
 class PyGridSim:
 	def __init__(self):
-		"""
-		Initialize OpenDSS/AltDSS engine. Creates an Empty Circuit
+		"""Initialize OpenDSS engine.
+
+		Instantiate an OpenDSS circuit that user can build circuit components on. Stores numbers of circuit components
+		to ensure unique naming of repeat circuit components
+		
+		Attributes:
+			num_loads (int): Number of loads in circuit so far.
+			num_lines (int): Number of lines in circuit so far.
+			num_transformers (int): Number of transformers in circuit so far.
+			num_pv (int): Number of PV systems in circuit so far.
+			num_generators (int): Number generators in circuit so far.
 		"""
 		self.num_loads = 0
 		self.num_lines = 0
@@ -19,115 +28,163 @@ def __init__(self):
 		altdss.ClearAll()
 		altdss('new circuit.MyCircuit')
 
-	def add_load_nodes(self, load_type: str = "house", params = {}, num: int = 1):
-		"""
-		When the user wants to manually add nodes, or make nodes with varying parameters.
+	def add_load_nodes(self, load_type: str = "house", params: dict[str, int] = None, num: int = 1):
+		"""Adds Load Node(s) to circuit.
+		
+		Allows the user to add num load nodes, either with customized parameters or using a default load_type.
 
 		Args: 
-			params: load parameters for these manual additions
-			load_type: input as string, representing one of the load types
-			lines: which nodes these new loads are connected to
-			num (optional): number of loads to create with these parameters
-		Return:
-			List of load_nodes
+			load_type (str, optional):
+				Load type as a string, one of "house", "commercial", "industrial". Defaults to "house".
+			params (dict[str, int], optional):
+				Load parameters for these manual additions. Defaults to empty dictionary.
+			num (int, optional):
+				The number of loads to create with these parameters. Defaults to 1.
+
+		Returns:
+			list[OpenDSS object]:
+				A list of OpenDSS objects representing the load nodes created.
 		"""
+		params = params or dict()
 		load_nodes = []
 		for _ in range(num):
-			make_load_node(params, load_type, self.num_loads)
+			_make_load_node(params, load_type, self.num_loads)
 			self.num_loads += 1
+
 		return load_nodes
 
-	def update_source(self, source_type: str = "turbine", params = {}):
-		"""
-		Adds a main voltage source if it doesn't exist, otherwise edits it
+	def update_source(self, source_type: str = "turbine", params: dict[str, int] = None):
+		"""Adds or updates source node in system.
+
+		If a Vsource node does not exist, it is created. Otherwise, its parameters are updated based on the provided values.
 
 		Args:
-			source_type: source type as a string
-			params: load parameters for these manual additions
-		Return:
-			List of source_nodes
-		"""
-		return make_source_node(params, source_type)
+			source_type (str, optional):
+				The type of the source (one of "turbine", "powerplant", "lvsub", "mvsub", "hvsub", "shvsub"). Defaults to "turbine".
+        	params (dict[str, int], optional):
+				A dictionary of parameters to configure the source node. Defaults to None.
 
-	def add_PVSystem(self, load_nodes: list[str], params = {}, num_panels: int = 1):
+		Returns:
+			OpenDSS object:
+				The OpenDSS object representing the source node.
 		"""
-		Specify a list of load nodes to add a PVsystem ("solar panel") to.
+		params = params or dict()
+		return _make_source_node(params, source_type)
+
+	def add_PVSystem(self, load_nodes: list[str], params: dict[str, int] = None, num_panels: int = 1):
+		"""Adds a photovoltaic (PV) system to the specified load nodes.
+
+		Adds PV system with num_panels to each of the listed load nodes. Can be customized with parameters.
 
 		Args:
-		    load_nodes: which load nodes to add PVsystem to
-			params: specify anything else about the PVsystem. otherwise defaults to typical solar panel
-			num_panels: representing how many solar panels (to represent scale)
-		Return:
-			list of PVSystem objects
+			load_nodes (list[str]):
+				A list of node names where the PV system will be connected.
+			params (dict[str, int], optional):
+				A dictionary of additional parameters for the PV system. Defaults to None.
+			num_panels (int, optional):
+				The number of PV panels in the system. Defaults to 1.
+
+		Returns:
+			list[DSS objects]:
+				A list of OpenDSS objects representing the PV systems created.
 		"""
+		params = params or dict()
 		if not load_nodes:
 			raise ValueError("Need to enter load nodes to add PVSystem to")
+
 		PV_nodes = []
 		for load in load_nodes:
-			PV_nodes.append(make_pv(load, params, num_panels, self.num_pv))
+			PV_nodes.append(_make_pv(load, params, num_panels, self.num_pv))
 			self.num_pv += 1
+
 		return PV_nodes
 
-	def add_generator(self, num: int = 1, gen_type: str = "small", params = {}):
-		"""
-		Specify parameters for a generator to add to the circuit
-
+	def add_generator(self, num: int = 1, gen_type: str = "small", params: dict[str, int] = None):
+		"""Adds generator(s) to the system.
+	
 		Args:
-			num: number of generators
-			gen_type: specify the generator type (small, large, industrial)
-			params: specify anything else about the generator.
-		Return:
-			list of generator objects
+			num (int, optional):  
+				The number of generator units to add. Defaults to 1.  
+			gen_type (str, optional):  
+				The type of generator (one of "small", "large", "industrial"). Defaults to "small".  
+			params (dict[str, int], optional):  
+				A dictionary of parameters to configure the generator. Defaults to None.  
+
+		Returns:
+			list[DSS objects]:
+				A list of OpenDSS objects representing the generators created.
 		"""
+		params = params or dict()
 		generators = []
 		for _ in range(num):
-			generators.append(make_generator(params, gen_type, count=self.num_generators))
+			generators.append(_make_generator(params, gen_type, count=self.num_generators))
 			self.num_generators += 1
+
 		return generators
 
 
-	def add_lines(self, connections: list[tuple], line_type: str = "lv", params = {}, transformer: bool = True):
-		"""
-		Specify all lines that the user wants to add. If redundant lines, doesn't add anything
+	def add_lines(self, connections: list[tuple], line_type: str = "lv", params: dict[str, int] = None, transformer: bool = True):
+		"""Adds lines to the system.
+
+		Adds electrical lines according to the given connections. Users can specify the parameters of the lines or otherwise use given line type options. 
 
 		Args:
-			connections: a list of new connections to add. Each item of the list follows the form (source1, load1)
-			line_type: a string representing linetype if user wants to use preset parameters
-			params: any custom parameters for lines or transformers
-			transformer: whether or not to include a transformer, default yes
+			connections (list[tuple]):  
+				A list of tuples defining the connections between nodes.  
+			line_type (str, optional):  
+				The type of line (one of "lv", "mv", "hv"). Defaults to "lv".  
+			params (dict[str, int], optional):  
+				A dictionary of parameters to configure the lines. Defaults to None.  
+			transformer (bool, optional):  
+				Whether to include a transformer in the connection. Defaults to True.  
+
+		Returns:
+			None
 		"""
+		params = params or dict()
 		for src, dst in connections:
-			make_line(src, dst, line_type, self.num_lines, params, transformer)
+			_make_line(src, dst, line_type, self.num_lines, params, transformer)
 			self.num_lines += 1
 
 	def solve(self):
-		"""
-		Initialize "solve" mode in AltDSS, then allowing the user to query various results on the circuit
+		"""Solves the OpenDSS circuit.
+
+		Initializes "solve" mode in OpenDSS, which then allows the user to query results on the circuit.
+
+		Returns:
+			None
 		"""
 		altdss.Solution.Solve()
 
 	def results(self, queries: list[str], export_path = ""):
-		"""
-		Allow the user to query for many results at once instead of learning how to manually query
+		"""Gets simulation results based on specified queries.
+	
+		Allows the user to query for many results at once by providing a list of desired queries.
 		
 		Args:
-			queries: List of queries to fetch the result of
-			export_path: if specified, exports result to this string
-		Return:
-			Results for each query, in a dictionary
+			queries (list[str]):  
+				A list of queries to the circuit ("Voltages", "Losses", "TotalPower")
+			export_path (str, optional):  
+				The file path to export results. If empty, results are not exported. Defaults to "".  
+
+		Returns:
+			dict:  
+				A dictionary containing the fetched simulation results.
 		"""
 		results = {}
 		for query in queries:
 			results[query] = query_solution(query)
+
 		if (export_path):
 			export_results(results, export_path)
+
 		return results
 
 	def clear(self):
-		"""
-		Must call after we are done using the circuit, or will cause re-creation errors.
+		"""Clears the OpenDSS circuit.
 
-		We only work with one circuit at a time, can only have one PyGridSim object at a time.
+		Returns:
+			None
 		"""
 		altdss.ClearAll()
 		self.num_loads = 0