PyLTSpice 5.3.2__tar.gz → 5.4.2__tar.gz

{pyltspice-5.3.2 → pyltspice-5.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: PyLTSpice
-Version: 5.3.2
+Version: 5.4.2
 Summary: A set of tools to Automate LTSpice simulations
 Author-email: Nuno Brum <me@nunobrum.com>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -685,10 +685,10 @@ Project-URL: Author, https://www.nunobrum.com/
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: spicelib>=1.2.1
+Requires-Dist: spicelib>=1.4.1
 
 # README #
 
@@ -1145,11 +1145,34 @@ _Make sure to initialize the root logger before importing the library to be able
 
 ## To whom do I talk to? ##
 
-* Tools website : [https://www.nunobrum.com/pyltspice.html](https://www.nunobrum.com/pyltspice.html)
-* Repo owner : [me@nunobrum.com](mailto:me@nunobrum.com)
-* Alternative contact : [nuno.brum@gmail.com](mailto:nuno.brum@gmail.com)
+For support and improvement requests please open an Issue in [GitHub spicelib issues](https://github.com/nunobrum/spicelib/issues)
 
 ## History ##
+* Version 5.4.2
+  * Imported changes from spicelib 1.4.1 (Summary)
+    * Added `get_all_parameter_names()` function to all editors (#159)
+    * Compatibility with LTspice 24+
+    * Fixed Problem with .PARAM regex.
+    * Documenting the user library paths
+    * AscEditor: Adding support to DATAFLAG
+    * LTSteps: Supporting new LTspice data export format
+* Version 5.4.1
+  * Fixing Issue #146
+* Version 5.4.0
+  * Adding possibility of manipulating parameters on sub-circuits
+  * Supporting subcircuit names with dots.
+  * Overall documentation improvements (thanks @hb020)
+  * Major improvement in Documentation
+  * Introduced a read-only property that blocks libraries from being updated.
+  * Support for LTspice log files with the option : expanded netlist
+  * Supporting library symbols using BLOCK primitive
+  * Improved unittest on the .ASC hierarchical design
+  * SimRunner simulation iterator only returns successful simulations in order to simplify error management
+  * In QschEditor, the replacement of unique dot instructions (ex: .TRAN .AC .NOISE) is only done if the existing instruction is not commented.
+  * RunTask.get_results() now returns None if a callback function is provided and the simulation has failed.
+  * BigFix: Inclusion of encrypted libraries would crash
+  * Bugfix: Prefix were case sensitive in SpiceEditor
+  * Bugfix: Parsing netlists with extensions other than .net didn't work properly
 * Version 5.3.2
   * Correction on the readthedocs webhook configuration
   * Alignement with the spicelib 1.2.1

pyltspice-5.4.2/PyLTSpice/LTSpiceBatch.py

@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""
+*(Deprecated)*
+Supporting Legacy import clauses. This will disappear in future versions
+"""
+print("Deprecation Warning! This will no longer be supported in future versions.\n"
+      "Use 'from PyLTSpice import SimCommander' for a direct import of the LTSpice/NGSpice batch run class.")
+
+from .sim.sim_batch import SimCommander

pyltspice-5.4.2/PyLTSpice/LTSpice_RawRead.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+"""
+*(Deprecated)*
+Supporting Legacy import clauses. This will disappear in future versions
+"""
+
+print("Deprecation Warning! This will no longer be supported in future versions.\n"
+      "Use 'from PyLTSpice import RawWRead' for a direct import of the Raw Reading class")
+
+from .raw.raw_read import *

pyltspice-5.4.2/PyLTSpice/LTSpice_RawWrite.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+"""
+*(Deprecated)*
+Supporting Legacy import clauses. This will disappear in future versions
+"""
+
+print("Deprecation Warning! This will no longer be supported in future versions.\n"
+      "Use 'from PyLTSpice import RawWRead' for a direct import of the Raw Write class")
+
+from .raw.raw_write import *

pyltspice-5.4.2/PyLTSpice/client_server/sim_client.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python
+# coding=utf-8
+
+# -------------------------------------------------------------------------------
+#    ____        _   _____ ____        _
+#   |  _ \ _   _| | |_   _/ ___| _ __ (_) ___ ___
+#   | |_) | | | | |   | | \___ \| '_ \| |/ __/ _ \
+#   |  __/| |_| | |___| |  ___) | |_) | | (_|  __/
+#   |_|    \__, |_____|_| |____/| .__/|_|\___\___|
+#          |___/                |_|
+#
+# Name:        sim_client.py
+# Purpose:     Tool used to launch LTSpice simulation in batch mode.
+#
+# Author:      Nuno Brum (nuno.brum@gmail.com)
+#
+# Created:     23-02-2023
+# Licence:     refer to the LICENSE file
+# -------------------------------------------------------------------------------
+import os.path
+import zipfile
+import xmlrpc.client
+import io
+import pathlib
+import time
+from collections import OrderedDict
+from dataclasses import dataclass
+import logging
+_logger = logging.getLogger("PyLTSpice.SimClient")
+
+class SimClientInvalidRunId(LookupError):
+    """Raised when asking for a run_no that doesn't exist"""
+    ...
+
+@dataclass
+class JobInformation:
+    """Contains information about pending simulation jobs"""
+    run_number: int  # The run id that is returned by the Server and which identifies the server
+    file_dir : pathlib.Path
+
+# class RunIterator(object):
+#
+#     def __init__(self, client, timeout):
+#         self.client = client
+#         self.timeout = timeout
+#
+#     def __iter__(self):
+#         return self
+#
+#     def __next__(self):
+#         return self.client.__next__()
+
+
+class SimClient(object):
+    """
+    Class used for launching simulations in a Spice Simulation Server.
+    A Spice Simulation Server is a machine running a script with an active SimServer object.
+
+    This class only implement basic level handshaking with a single simulation Server.
+    Upon instance, it will establish a connection with Simulation Server. This connection is kept
+    alive during the whole live of this object.
+
+    The run() method will transfer the netlist for the server, execute a simulation and transfer the simulation results
+    back to the client.
+
+    Data is returned from the server inside a zipfie which is copied into the directory defined when the job was
+    created, /i.e./ run() method called.
+
+    Two lists are kept by this class:
+
+        * A list of started jobs (started_jobs) and,
+
+        * a list with finished jobs on the server, but, which haven't been yet transferred to the client (stored_jobs).
+
+    This distinction is important because the data is erased on the server side when the data is transferred.
+
+    This class implements an iterator that is to be used for retrieving the job. See the example below.
+    The iterator polls the server with a time interval defined by the attribute ``minimum_time_between_server_calls``.
+    This attribute is set to 0.2 seconds by default, but it can be overriden.
+
+    Usage:
+
+    .. code-block:: python
+
+        import zipfile
+        from PySpice.sim.sim_client import SimClient
+
+        server = SimClient('http://localhost', 9000)  # Use another computer address.
+        print(server.session_id)
+        runid = server.run("../../tests/testfile.net")
+        print("Got Job id", runid)
+
+        for runid in server:   # may not arrive in the same order as runids were launched
+            zip_filename = server.get_runno_data(runid)
+            print(f"Received {zip_filename} from runid {runid}")
+
+            with zipfile.ZipFile(zip_filename, 'r') as zipf:  # Extract the contents of the zip file
+                print(zipf.namelist())  # Debug printing the contents of the zip file
+                zipf.extract(zipf.namelist()[0])  # Normally the raw file comes first
+
+    NOTE: More elaborate algorithms such as managing multiple servers will be done on another class.
+    """
+
+    def __init__(self, host_address, port):
+        self.server = xmlrpc.client.ServerProxy(f'{host_address}:{port}')
+        # print(self.server.system.listMethods())
+        self.session_id = self.server.start_session()
+        _logger.info("started ", self.session_id)
+        self.started_jobs = OrderedDict()  # This list keeps track of started jobs on the server
+        self.stored_jobs = OrderedDict()  # This list keeps track of finished simulations that haven't yet been transferred.
+        self.completed_jobs = 0
+        self.minimum_time_between_server_calls = 0.2  # Minimum time between server calls
+        self._last_server_call = time.clock()
+
+    def __del__(self):
+        _logger.info("closing session ", self.session_id)
+        self.server.close_session(self.session_id)
+
+    def run(self, circuit):
+        """
+        Sends the netlist identified with the argument "circuit" to the server, and it receives a run identifier
+        (runno). Since the server can receive requests from different machines, this identifier is not guaranteed to be
+        sequential.
+
+        :param circuit: path to the netlist file containing the simulation directives.
+        :type circuit: pathlib.Path or str
+        :returns: identifier on the server of the simulation.
+        :rtype: int
+        """
+        circuit_path = pathlib.Path(circuit)
+        circuit_name = circuit_path.name
+        if os.path.exists(circuit):
+            # Create a buffer to store the zip file in memory
+            zip_buffer = io.BytesIO()
+
+            # Create the zip file in memory
+            with zipfile.ZipFile(zip_buffer, 'w', zipfile.ZIP_DEFLATED) as zip_file:
+                zip_file.write(circuit, circuit_name)  # Makes sure it writes it to the root of the zipfile
+
+            # Reset the buffer position to the start
+            zip_buffer.seek(0)
+
+            # Read the zip file from the buffer and send it to the server
+            zip_data = zip_buffer.read()
+
+            run_id = self.server.run(self.session_id, circuit_name, zip_data)
+            job_info = JobInformation(run_number=run_id, file_dir=circuit_path.parent)
+            self.started_jobs[job_info] = job_info
+            return run_id
+        else:
+            _logger.error(f"Circuit {circuit} doesn't exit")
+            return -1
+        
+    def get_runno_data(self, runno) -> str:
+        """
+        Returns the simulation output data inside a zip file name.
+
+        :rtype: str
+        """
+        if runno not in self.stored_jobs:
+            raise SimClientInvalidRunId(f"Invalid Job id {runno}")
+
+        zip_filename, zipdata = self.server.get_files(self.session_id, runno)
+        job = self.stored_jobs.pop(runno)  # Removes it from stored jobs
+        self.completed_jobs += 1
+        if zip_filename != '':
+            store_path = job.file_dir
+            with open(store_path / zip_filename, 'wb') as f:
+                f.write(zipdata.data)
+        return zip_filename
+
+    def __iter__(self):
+        return self
+    
+    def __next__(self):
+        while len(self.started_jobs) > 0:
+            status = self.server.status(self.session_id)
+            if len(status) > 0:
+                runno = status.pop(0)
+                self.stored_jobs[runno] = self.started_jobs.pop(runno)  # Job is taken out of the started jobs list and
+                # is added to the stored jobs
+                return runno
+            else:
+                now = time.clock()
+                delta = self.minimum_time_between_server_calls - (now - self._last_server_call)
+                if delta > 0:
+                    time.sleep(delta)  # Go asleep for a sec
+                self._last_server_call = now
+
+        # when there are no pending jobs left, exit the iterator    
+        raise StopIteration
+        
+
+if __name__ == "__main__":
+
+    server = SimClient('http://localhost', 9000)
+    print(server.session_id)
+    runid = server.run("../../tests/testfile.net")
+    print("Got Job id", runid)
+    for runid in server:  # Ma
+        zip_filename = server.get_runno_data(runid)
+        print(f"Received {zip_filename} from runid {runid}")
+        with zipfile.ZipFile(zip_filename, 'r') as zipf:  # Extract the contents of the zip file
+            print(zipf.namelist())  # Debug printing the contents of the zip file
+            zipf.extract(zipf.namelist()[0])  # Normally the raw file comes first
+
+    print("Finished")
+    server.server.stop_server()  # This will terminate the server

pyltspice-5.4.2/PyLTSpice/client_server/sim_server.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python
+# coding=utf-8
+
+# -------------------------------------------------------------------------------
+#    ____        _   _____ ____        _
+#   |  _ \ _   _| | |_   _/ ___| _ __ (_) ___ ___
+#   | |_) | | | | |   | | \___ \| '_ \| |/ __/ _ \
+#   |  __/| |_| | |___| |  ___) | |_) | | (_|  __/
+#   |_|    \__, |_____|_| |____/| .__/|_|\___\___|
+#          |___/                |_|
+#
+# Name:        sim_server.py
+# Purpose:     Tool used to launch LTSpice simulation in batch mode.
+#
+# Author:      Nuno Brum (nuno.brum@gmail.com)
+#
+# Created:     23-02-2023
+# Licence:     refer to the LICENSE file
+# -------------------------------------------------------------------------------
+from typing import Tuple
+from xmlrpc.client import Binary
+from xmlrpc.server import SimpleXMLRPCServer
+import logging
+_logger = logging.getLogger("PyLTSpice.SimServer")
+
+import threading
+import zipfile
+import io
+from PyLTSpice.client_server.srv_sim_runner import ServerSimRunner
+import uuid
+
+
+class SimServer():
+
+    def __init__(self, simulator, parallel_sims=4, output_folder='./temp1', port=9000):
+        self.output_folder = output_folder
+        self.simulation_manager = ServerSimRunner(parallel_sims=parallel_sims, timeout=5 * 60, verbose=True,
+                                                  output_folder=output_folder, simulator=simulator)
+        self.server = SimpleXMLRPCServer(
+                ('localhost', port),
+                # requestHandler=RequestHandler
+        )
+        self.server.register_introspection_functions()
+        self.server.register_instance(self)
+        self.sessions = {}  # this will contain the session_id ids hashing their respective list of sim_tasks
+        self.simulation_manager.start()
+        self.server_thread = threading.Thread(target=self.server.serve_forever, name="ServerThread")
+        self.server_thread.start()
+
+    def run(self, session_id, circuit_name, zip_data):
+        _logger.info("Run ", session_id, circuit_name)
+        if session_id not in self.sessions:
+            return -1  # This indicates that no job is started
+        # Create a buffer from the zip data
+        zip_buffer = io.BytesIO(zip_data.data)
+        _logger.debug("Created the buffer")
+        # Extract the contents of the zip file
+        with zipfile.ZipFile(zip_buffer, 'r') as zip_file:
+            _logger.debug(zip_file.namelist())
+            zip_file.extract(circuit_name, self.output_folder)
+
+        _logger.info(f"Running simulation of {circuit_name}")
+        runno = self.simulation_manager.add_simulation(circuit_name)
+        if runno != -1:
+            self.sessions[session_id].append(runno)
+        return runno
+
+    def start_session(self):
+        """Returns an unique key that represents the session. It will be later used to sort the sim_tasks belonging
+        to the session."""
+        session_id = str(uuid.uuid4())  # Needs to be a string, otherwise the rpc client can't handle it
+        _logger.info("Starting session ", session_id)
+        self.sessions[session_id] = []
+        return session_id
+
+    def status(self, session_id):
+        """
+        Returns a dictionary with task information. The key for the dictionary is the simulation identifier returned
+        by the simulation start command. The value associated with each simulation identifier is another dictionary
+        containing the following keys:
+
+            * 'completed' - whether the simulation is already finished
+
+            * 'start' - time when the simulation was started
+
+            * 'stop' - server time
+        """
+        _logger.debug("collecting status for ", session_id)
+        ret = []
+        for task_info in self.simulation_manager.completed_tasks:
+            _logger.debug(task_info)
+            runno = task_info['runno']
+            if runno in self.sessions[session_id]:
+                ret.append(runno)  # transfers the dictionary from the simulation_manager completed task
+                # to the return dictionary 
+        _logger.debug("returning status", ret)
+        return ret
+
+    def get_files(self, session_id, runno) -> Tuple[str, Binary]:
+        if runno in self.sessions[session_id]:
+
+            for task_info in self.simulation_manager.completed_tasks:
+                if runno == task_info['runno']:
+                    # Create a buffer to store the zip file in memory
+                    zip_file = task_info['zipfile']
+                    zip = zip_file.open('rb')
+                    # Read the zip file from the buffer and send it to the server
+                    zip_data = zip.read()
+                    zip.close()
+                    self.simulation_manager.erase_files_of_runno(runno)
+                    return zip_file.name, Binary(zip_data)
+
+        return "", Binary(b'')  # Returns and empty data
+
+    def close_session(self, session_id):
+        """Cleans all the pending sim_tasks with """
+        for runno in self.sessions[session_id]:
+            self.simulation_manager.erase_files_of_runno(runno)
+        return True  # Needs to return always something. None is not supported
+
+    def stop_server(self):
+        _logger.info("stopping...ServerInterface")
+        self.simulation_manager.stop()
+        self.server.shutdown()
+        _logger.info("stopped...ServerInterface")
+        return True  # Needs to return always something. None is not supported
+
+    def running(self):
+        return self.simulation_manager.running()
+

pyltspice-5.4.2/PyLTSpice/client_server/srv_sim_runner.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python
+# coding=utf-8
+
+# -------------------------------------------------------------------------------
+#    ____        _   _____ ____        _
+#   |  _ \ _   _| | |_   _/ ___| _ __ (_) ___ ___
+#   | |_) | | | | |   | | \___ \| '_ \| |/ __/ _ \
+#   |  __/| |_| | |___| |  ___) | |_) | | (_|  __/
+#   |_|    \__, |_____|_| |____/| .__/|_|\___\___|
+#          |___/                |_|
+#
+# Name:        srv_sim_runner.py
+# Purpose:     Manager of the simulation sim_tasks on the server side
+#
+# Author:      Nuno Brum (nuno.brum@gmail.com)
+#
+# Created:     23-02-2023
+# Licence:     refer to the LICENSE file
+# -------------------------------------------------------------------------------
+import threading
+import time
+from typing import Any, Callable, Union
+from pathlib import Path
+import zipfile
+import logging
+_logger = logging.getLogger("PyLTSpice.ServerSimRunner")
+
+from PyLTSpice.sim.sim_runner import SimRunner
+from PyLTSpice.sim.spice_editor import SpiceEditor
+
+
+def zip_files(raw_filename: Path, log_filename:Path):
+    zip_filename = raw_filename.with_suffix('.zip')
+    with zipfile.ZipFile(zip_filename, 'w', zipfile.ZIP_DEFLATED) as zip_file:
+        zip_file.write(raw_filename)
+        zip_file.write(log_filename)
+    return zip_filename
+
+
+class ServerSimRunner(threading.Thread):
+    """This class maintains updated status of the SimRunner.
+    It was decided not to make SimRunner a super class and rather make it manipulate directly the structures of
+    SimRunner. The rationale for this, was to avoid confusions between the run() on the Thread class and the
+    run on the SimRunner class.
+    Making a class derive from two different classes needs to be handled carefully.
+
+    In consequence of the rationale above, many of the functions that were handled by the SimRunner are overriden
+    by this class.
+    """
+
+    def __init__(self, parallel_sims: int = 4, timeout=None, verbose=True, output_folder: str = None, simulator=None):
+        super().__init__(name="SimManager")
+        self.runner = SimRunner(parallel_sims, timeout, verbose, output_folder, simulator)
+        self.completed_tasks = []
+        self._stop = False
+
+    def run(self) -> None:
+        """This function makes a direct manipulation of the structures of SimRunner. This option is """
+        while True:
+            i = 0
+            while i < len(self.runner.sim_tasks):
+                task = self.runner.sim_tasks[i]
+                if task.is_alive():
+                    i += 1
+                else:
+                    zip_filename = task.callback_return
+                    self.completed_tasks.append({
+                        'runno': task.runno,
+                        'retcode': task.retcode,
+                        'raw': task.raw_file,
+                        'log': task.log_file,
+                        'zipfile': zip_filename,
+                        'start': task.start_time,
+                        'stop': task.stop_time,
+                    })
+                    _logger.debug(task, "is finished")
+                    del self.runner.sim_tasks[i]
+                    _logger.debug(self.completed_tasks[-1])
+                    _logger.debug(len(self.completed_tasks))
+
+            time.sleep(0.2)
+            if self._stop is True:
+                break
+        self.runner.wait_completion()
+        self.runner.file_cleanup()
+
+    def add_simulation(self, netlist: Union[str, Path, SpiceEditor], *, timeout: float = 600) -> int:
+        """"""
+        _logger.debug("starting ", netlist)
+        task = self.runner.run(netlist, wait_resource=True, timeout=timeout, callback=zip_files)
+        if task is None:
+            _logger.error("Failed to start task ", netlist)
+            return -1
+        else:
+            _logger.info("Started task ", netlist, " with job_id", task.runno)
+            return task.runno
+
+    def _erase_files_and_info(self, pos):
+        task = self.completed_tasks[pos]
+        for filename in ('log', 'raw', 'zipfile'):
+            f = task[filename]
+            if f.exists():
+                f.unlink()
+        del self.completed_tasks[pos]
+
+    def erase_files_of_runno(self, runno):
+        """Will delete all files related with a completed task. Will also delete information on the completed_tasks
+        attribute."""
+        for i, task_info in enumerate(self.completed_tasks):
+            if task_info['runno'] == runno:
+                self._erase_files_and_info(i)
+                break
+
+    def cleanup_completed(self):
+        while len(self.completed_tasks):
+            self._erase_files_and_info(0)
+
+    def stop(self):
+        _logger.info("stopping...ServerSimRunner")
+        self._stop = True
+
+    def running(self):
+        return self._stop is False