PyELSSA 0.1.0__tar.gz

pyelssa-0.1.0/LICENSE

@@ -0,0 +1,88 @@
+Copyright (c) 2026 [Jieming Ye, Engineering Services Design]
+
+Open Source Non-Commercial License (OSNCL) v2.0
+
+                                            Preamble
+The purpose of this license is to ensure that the software remains free for non-commercial use, while also ensuring 
+that any modifications to the software are made publicly available. Commercial use of this software is not allowed 
+without prior written permission from the original author(s).
+
+The precise terms and conditions for copying, distribution, and modification follow.
+
+                                       TERMS AND CONDITIONS
+Section 0: Definitions
+
+“This License” refers to version 2.0 of the Open Source Non-Commercial License.
+“The Software” refers to the Python package and all associated files, including but not limited to source code, 
+documentation, and configuration files, distributed under this License.
+“Modification” means any work derived from or based on the Software, such as bug fixes, enhancements, or other 
+alterations to the original work.
+"E&P Team" refers to the E&P team under Engineering Services, Route Services, Network Rail Infrastructure Ltd, 
+structured at September 2024.
+“You” refers to the individual or entity using, modifying, or distributing the Software.
+
+“Public Distribution” refers to the act of making any modifications of the Software available to the general 
+public.
+
+Section 1: Source Code and Modifications
+
+1.1 You may modify the Software and distribute your modified version, provided that:
+You make the source code of the modified version available to the public under the same terms as this License.
+The modified version must be clearly marked to indicate that changes have been made, including the date of changes.
+
+1.2 All modifications must be publicly available, in a manner that makes them easily accessible, such as posting 
+on a public repository (e.g., GitHub, GitLab).
+
+Section 2: Non-Commercial Use
+
+2.1 You may use, distribute, and modify the Software for non-commercial purposes only, including:
+Personal projects.
+Educational purposes.
+Research purposes.
+
+2.2 Commercial use of the Software is prohibited unless you have received explicit, prior written permission 
+from the original author(s).
+
+2.3 If you wish to make commercial use of the Software, including any modifications, you must contact the original 
+author(s) to seek permission and negotiate terms for such use.
+
+Section 3: Conveying Modified Source Code
+
+3.1 If you modify the Software, you must:
+Ensure that the modifications are licensed under this License.
+Make the modified source code publicly available.
+Provide information in any modified version about the changes made, including a notice stating the date of the 
+modification and who made the changes.
+
+Section 4: Conveying Non-Source Forms
+
+4.1 You may convey non-source forms of the Software, such as compiled binaries, provided that:
+You also provide access to the corresponding source code.
+The source code is made available under the same terms as this License.
+
+Section 5: Commercial Use Exception
+
+5.1 Commercial use of the Software or any modified versions is strictly prohibited unless permission is granted 
+in writing by the original author(s). For commercial inquiries, please contact [Traction.Power@networkrail.co.uk].
+
+5.2 Commercial use of the Software or any modified versions is allowed by [E&P Team] without any restriction.
+
+Section 6: No Warranty
+
+6.1 There is no warranty for the Software, to the extent permitted by applicable law. The Software is provided 
+“as is” without warranty of any kind, either expressed or implied, including but not limited to the implied 
+warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and 
+performance of the Software is with you.
+
+6.2 In no event, unless required by law or agreed to in writing, shall the author(s) be liable for any damages, 
+including any general, special, incidental, or consequential damages arising from the use or inability to use the 
+Software.
+
+Section 7: Termination
+
+7.1 You may not propagate or modify the Software except as expressly provided under this License. Any attempt 
+otherwise to propagate or modify the Software is void and will automatically terminate your rights under this 
+License.
+
+7.2 However, parties who have received copies, or rights, from you under this License will not have their 
+licenses terminated so long as they remain in full compliance.

pyelssa-0.1.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: PyELSSA
+Version: 0.1.0
+Summary: This is 'ELSSA in Python' package owned by Network Rail Infrastructure Limited.
+License: Open Source Non-Commercial License (OSNCL) v2.0
+License-File: LICENSE
+Author: Jieming Ye
+Author-email: Jieming.Ye@networkrail.co.uk
+Requires-Python: >=3.10
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: psutil
+Requires-Dist: scipy
+Requires-Dist: tk
+Project-URL: Homepage, https://pypi.org/project/PyELSSA/
+Description-Content-Type: text/markdown
+
+# ELSSA_python
+ELSSA (Electrification System Simulation Analysis) was written in Matlab. The last supporting Matlab version is 2014a which is out of official support for a fairly long time.
+Some of the source file is p coded (encrypted) which makes the support extremly difficult.
+
+This repository looks to mordenlize the software suite to a new era, giving the technology involvement in the last decade.
+
+The code will be rewritten from scratch in Python aiming for better user interface and program maintenance.
+
+## ELSSA Python Migration Plan
+- Phase 1: Reverse engineering the p coded section.
+- Phase 2: Replicate the ELSSA Matlab functionality.
+- Phase 3: Enhance the tool package and user interface. 
+
+
+## ELLSA Matlab
+Please refer to: https://github.com/NR-ESTractionPower/ELSSA_matlab
+
+

pyelssa-0.1.0/README.md

@@ -0,0 +1,17 @@
+# ELSSA_python
+ELSSA (Electrification System Simulation Analysis) was written in Matlab. The last supporting Matlab version is 2014a which is out of official support for a fairly long time.
+Some of the source file is p coded (encrypted) which makes the support extremly difficult.
+
+This repository looks to mordenlize the software suite to a new era, giving the technology involvement in the last decade.
+
+The code will be rewritten from scratch in Python aiming for better user interface and program maintenance.
+
+## ELSSA Python Migration Plan
+- Phase 1: Reverse engineering the p coded section.
+- Phase 2: Replicate the ELSSA Matlab functionality.
+- Phase 3: Enhance the tool package and user interface. 
+
+
+## ELLSA Matlab
+Please refer to: https://github.com/NR-ESTractionPower/ELSSA_matlab
+

pyelssa-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+
+[tool.poetry]
+name = "PyELSSA"
+version = "0.1.0"
+description = "This is 'ELSSA in Python' package owned by Network Rail Infrastructure Limited."
+authors = ["Jieming Ye <Jieming.Ye@networkrail.co.uk>"]
+readme = "README.md"
+include = ["src"]
+exclude = ["src/PyELSSA/core/*"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: Other/Proprietary License",
+    "Operating System :: OS Independent",
+]
+license = "Open Source Non-Commercial License (OSNCL) v2.0"
+urls = { Homepage = "https://pypi.org/project/PyELSSA/" }
+
+
+# Add this line to reference the requirements.txt file
+[tool.poetry.dependencies]
+python = ">=3.10"
+tk = "*"
+numpy = "*"
+pandas = "*"
+matplotlib = "*"
+scipy = "*"
+psutil = "*"
+
+[tool.poetry.group.dev.dependencies]
+flake8 = "*"
+pytest = "*"

pyelssa-0.1.0/src/PyELSSA/__init__.py

@@ -0,0 +1,28 @@
+#
+# -*- coding: utf-8  -*-
+#=================================================================
+# Created by: Jieming Ye
+# Created on: Sep 2026
+# Last Modified: XX/XX/2026
+#=================================================================
+# Copyright (c) 2026 [Jieming Ye]
+#
+# This Python source code is licensed under the 
+# Open Source Non-Commercial License (OSNCL) v1.0
+# See LICENSE for details.
+#=================================================================
+"""
+Python on ELSSA: PyELSSA Package
+
+"""
+#=================================================================
+# VERSION CONTROL
+# V1.0.0 (Jieming Ye) - Initial Version
+#=================================================================
+# Set Information Variable
+__author__ = "Jieming Ye"
+__copyright__ = "Copyright 2026, Engineering Services"
+__credits__ = "Jieming Ye"
+__version__ = "0.1.0"
+__email__ = "jieming.ye@networkrail.co.uk"
+__status__ = "Beta Version"

pyelssa-0.1.0/src/PyELSSA/configuration.py

@@ -0,0 +1,325 @@
+#
+# -*- coding: utf-8  -*-
+#=================================================================
+# Created by: Jieming Ye
+# Created on: July 2026
+# Last Modified: July 2026
+#=================================================================
+# Copyright (c) 2026 [Jieming Ye]
+#
+# This Python source code is licensed under the 
+# Open Source Non-Commercial License (OSNCL) v1.0
+# See LICENSE for details.
+#=================================================================
+"""
+This scripts contains the functions that control the configuration file settings
+
+"""
+#=================================================================
+# VERSION CONTROL
+# V1.0 (Jieming Ye) - Initial Version
+#
+#=================================================================
+# Set Information Variable
+# N/A
+#=================================================================
+
+import os
+import json
+import importlib
+import requests
+import shutil
+
+from PyELSSA.shared_contents import SharedVariables, SharedMethods, DataFilenames, InternetValidation
+from PyELSSA.shared_msazure_api import AzureWorkflow, AzureCloudID
+
+CONFIG_FILE = SharedVariables.config_file
+
+# initial database system check
+def initial_missing_user_database_check():
+    '''
+    This function doing application database entering checking and returing:
+    FALSE: if the initial database check passed i.e. no missing files.
+    Filenamelist: if the initial database check failed.
+    '''
+    filenamelist = []
+    # check if the database path exist.
+    if not os.path.exists(SharedVariables.database_path_user):
+        for filename in DataFilenames.private_file.values():
+            filenamelist.append(filename)
+        for filename in DataFilenames.public_file.values():
+            filenamelist.append(filename)
+    
+    # loop the database folder and add the missing files into the filename list
+    else:
+        for filename in DataFilenames.private_file.values():
+            file_in_package = os.path.join(SharedVariables.database_path_user, filename)
+            if not os.path.isfile(file_in_package):
+                filenamelist.append(filename)
+        for filename in DataFilenames.public_file.values():
+            file_in_package = os.path.join(SharedVariables.database_path_user, filename)
+            if not os.path.isfile(file_in_package):
+                filenamelist.append(filename)
+
+    # if not empty filename list return filenamelist otherwise False
+    if filenamelist:
+        return filenamelist
+    else:
+        return False
+
+# update the customised database library
+@staticmethod
+def update_database_library(filenamelist: list=None, library: int = 0):
+    '''
+    This function updates the customised database library from GitHub Repo online (if public)
+    or data folder (if private).
+    This will overwrite the existing database file blindly.
+
+    if no input is not provided, this will restore all default database library
+
+    library: (int)
+    default to 0: default library
+    1: user library
+    '''
+    if library == 0:
+        controlled_data_path = SharedVariables.database_path_default
+    else:
+        controlled_data_path = SharedVariables.database_path_user
+
+    print(f"Config Path: '{controlled_data_path}'")
+
+    os.makedirs(controlled_data_path, exist_ok=True)
+    
+    private_file_list = []
+    public_file_list = []
+
+    if filenamelist:
+        for filename in filenamelist:
+            # check if the filename belongs public or private dataset, and update accordingly
+            if filename in DataFilenames.private_file.values():
+                private_file_list.append(filename)
+            elif filename in DataFilenames.public_file.values():
+                public_file_list.append(filename)
+            else:
+                SharedMethods.print_message(f"ERROR: File '{filename}' is not recognised as a valid database file. Please contact support using this error message...", "31")
+                return False
+    else: # default to updating all database files
+        for file in DataFilenames.private_file.values():
+            private_file_list.append(file)
+        for file in DataFilenames.public_file.values():
+            public_file_list.append(file)
+    
+    # copy the private data from the packaged data folder
+    distribution = importlib.resources.files(SharedVariables.package_name)
+    package_path = os.path.join(str(distribution), SharedVariables.private_data_name)
+
+    # Get the absolute path of the file in the package location
+    for file in private_file_list:
+        file_in_package = os.path.join(package_path, file)
+        target_file = os.path.join(controlled_data_path, file)
+        try:
+            shutil.copy(file_in_package, target_file)
+            SharedMethods.print_message(f"ATTENTION: '{file}' database updated to default dataset.","33")
+        except Exception as e:
+            SharedMethods.print_message(f"ERROR: Error copying file {file} to {target_file}: {e}. Please contact support using this error message...", "31")
+            return False
+    
+    # check online resources and download the public data to the same folder
+    # Check internet connection
+    if not InternetValidation.internet_check(SharedVariables.public_data_path):
+        SharedMethods.print_message(f"WARNING: Online databse updated cannot proceed due to not allowed network. Skipping...","33")
+        return False
+    
+    for file in public_file_list:
+        file_url = SharedVariables.raw_data_url_begin + file
+        # download the csv file to the target folder
+        target_file = os.path.join(controlled_data_path, file)
+        try:
+            response = requests.get(file_url)
+            response.raise_for_status()  # Raise an error for bad responses
+            with open(target_file, 'wb') as f:
+                f.write(response.content)
+            SharedMethods.print_message(f"ATTENTION: '{file}' database updated to default dataset.","33")
+        except Exception as e:
+            SharedMethods.print_message(f"ERROR: Error downloading file {file} from {file_url}: {e}. Please contact support using this error message...", "31")
+            return False
+        
+    return True
+
+# reset configuraiton file varile to default
+def reset_configuration_file_varible(key: str = "DEFAULT_ALL"):
+    """
+    This function reset configuration varible to default
+    return True of False
+    """
+    try:
+        if not os.path.exists(SharedVariables.config_file):
+            SharedMethods.print_message(f"ERROR: Configuration file not found. ","31")
+            return False
+
+        config_data = DataFilenames.default_config
+
+        if key == "DEFAULT_ALL": 
+            with open(SharedVariables.config_file, "w") as file:
+                json.dump(config_data, file, indent=4)
+            return True
+        else:
+            return set_configuration_file_variable(key,config_data[key]) 
+
+    except Exception as e:
+        SharedMethods.print_message(f"ERROR: Error resetting configuration: {e}","31")
+        return False
+
+
+# set configuration file
+def set_configuration_file_variable(key:str, value):
+    """
+    This function handle the configuration file value update
+    return True or False
+    """
+    try:
+        if not os.path.exists(CONFIG_FILE):
+            SharedMethods.print_message(f"ERROR: Configuration file not found. ","31")
+            return False
+        
+        with open(CONFIG_FILE, "r") as file:
+            config_data = json.load(file)
+        
+        if config_data.get(key) != value:
+            config_data[key] = value
+            with open(CONFIG_FILE, "w") as file:
+                json.dump(config_data, file, indent=4)
+        return True
+
+    except Exception as e:
+        SharedMethods.print_message(f"ERROR: Error setting configuration: {e}","31")
+        return False
+    
+# read configuration file varible
+def read_configuration_file_variable(key:str, update_required: bool = False):
+    """
+    This function read the configuration file and return value
+    return Value or False / None
+    """
+    try:
+        if not os.path.exists(CONFIG_FILE):
+            SharedMethods.print_message(f"ERROR: Configuration file not found. ","31")
+            return False
+
+        config_data = {}
+        with open(CONFIG_FILE, "r") as file:
+            config_data = json.load(file)
+        
+        if key not in config_data:
+            SharedMethods.print_message(f"WARNING: Configuration does not contain setting of {key}. ","33")
+            if update_required:
+                SharedMethods.print_message(f"WARNING: {key} will be set to default value. ","33")
+            return False
+        
+        return config_data[key]
+
+    except Exception as e:
+        SharedMethods.print_message(f"ERROR: Error reading configuration: {e}","31")
+        return False
+
+def version_updated():
+    try:
+        if os.path.exists(SharedVariables.config_file):
+            with open(SharedVariables.config_file, 'r') as file:
+                config_data = json.load(file)
+                if not config_data["package_version_number"] == SharedVariables.installed_version:
+                    return True
+        return False
+    except Exception as e:
+        SharedMethods.print_message(f"ERROR: Error reading configuration: {e}","31")
+        return False
+
+def update_elssa_core():
+    try:
+        # ensure the installation folder location exist
+        if os.path.exists(SharedVariables.package_path):
+            # validate if configuration path folder exist if not, create it
+            os.makedirs(SharedVariables.elssa_core_path, exist_ok=True)
+            # download the latest
+            if not AzureWorkflow.download_tdns_sharepoint_folder(AzureCloudID.DOC_LIBRARY,AzureCloudID.ELSSA_CORE_PATH,SharedVariables.elssa_core_path,True):
+                return False
+            return True
+
+        else:
+            SharedMethods.print_message(f"ERROR: {SharedVariables.package_name} has not been installed yet...","31")
+            return False
+    except Exception as e:
+        SharedMethods.print_message(f"ERROR: Error updating the PyELSSA core: {e}","31")
+        SharedMethods.print_message(f"ERROR: Please check the message above. Try again with proper internet or contact support...","31")
+        return False
+
+# processing of checking configuraiton file and set up approprite action
+def configuration_main():
+    # disable in debug mode (bypass the process in debug mode):
+    if SharedMethods.is_debug_mode():
+        return True
+
+    # validate if configuration path folder exist if not, create it
+    os.makedirs(SharedVariables.configuration_path, exist_ok=True)
+
+    # update default database if configuration file does not exist (1st run only)
+    if not os.path.exists(CONFIG_FILE):
+        # create empty configuration file.
+        try:
+            with open(CONFIG_FILE, "w") as file:
+                json.dump({}, file)
+        except Exception as e:
+            SharedMethods.print_message(f"ERROR: Error creating configuration: {e}","31")
+            return False
+    
+    # version update steps
+    try:
+        if version_updated():
+            # after the version udpate, elssa core is forced to be update, set to false
+            set_configuration_file_variable(key = 'elssa_core_updated',value = False)
+
+        # download the ELSSA core from the SharePoint
+        if not read_configuration_file_variable(key = 'elssa_core_updated'):
+            # trying the update the default library if success or not.
+            if not update_elssa_core():
+                # update not successful, force exit until update completed to ensure consistent version
+                return False
+            else:
+                # write the status to json configuraiton file
+                set_configuration_file_variable(key = 'elssa_core_updated',value = True)
+                SharedMethods.print_message(f"INFO: ELSSA Core Package Updating Succesfully. Consider relauch the application for proper reloading.","32")
+
+        if not read_configuration_file_variable(key = 'default_database_updated', update_required = True):
+            # trying the update the default library if success or not.
+            if not update_database_library():
+                # update not successful
+                database_library = False
+            else:
+                # update succesfully
+                database_library = True
+            # write the status to json configuraiton file
+            set_configuration_file_variable(key = 'default_database_updated',value = database_library)
+
+        set_configuration_file_variable(key = 'package_version_number', value = SharedVariables.installed_version)
+        return True
+
+    except Exception as e:
+        SharedMethods.print_message(f"ERROR: Error reading / writing configuration: {e}","31")
+        return False
+
+
+def main():
+    if not configuration_main():
+        SharedMethods.print_message(f"ERROR: Configuration environment is not set properly. Close and try it again...","31")
+        SharedMethods.print_message(f"ERROR: Contact support {SharedVariables.contacts} if the issue persist...","31")
+        return False
+    else:
+        # database folder check: This is on customised user database only
+        filenamelist = initial_missing_user_database_check()
+        if filenamelist:
+            update_database_library(filenamelist=filenamelist,library=1)
+        return True
+
+# Programme running
+if __name__ == '__main__':
+    main()