ltbams 0.9.9__py3-none-any.whl → 1.0.0__py3-none-any.whl

ams/utils/misc.py

@@ -0,0 +1,77 @@
+import warnings
+import functools
+
+from andes.utils.misc import elapsed
+
+
+def timer(func):
+    def wrapper(*args, **kwargs):
+        t0, _ = elapsed()
+        result = func(*args, **kwargs)
+        _, s = elapsed(t0)
+        return result, s
+    return wrapper
+
+
+def create_entry(*fields, three_params=True):
+    """
+    Helper function to create a list of fields for a model entry.
+
+    Parameters
+    ----------
+    fields : tuple
+        Additional fields to include in the list.
+    three_params : bool, optional
+        Whether to include 'idx', 'u', 'name' in the list (default is True).
+
+    Returns
+    -------
+    list
+        A list of fields for the model entry.
+    """
+    base_fields = ['idx', 'u', 'name'] if three_params else []
+    return base_fields + list(fields)
+
+
+def pretty_long_message(message, prefix="", max_length=80):
+    """
+    Pretty print a long message.
+
+    Parameters
+    ----------
+    message : str
+        The message to format.
+    prefix : str, optional
+        A prefix to add to each line of the message.
+    max_length : int, optional
+        The maximum length of each line.
+
+    Returns
+    -------
+    str
+        The formatted message.
+    """
+    if len(message) <= max_length:
+        return message
+    else:
+        lines = [message[i:i+max_length] for i in range(0, len(message), max_length)]
+        formatted_message = lines[0] + "\n" + "\n".join([prefix + line for line in lines[1:]])
+        return formatted_message
+
+
+def deprecated(message="This function is deprecated and will be removed in a future version."):
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            warnings.warn(
+                message,
+                category=DeprecationWarning,
+                stacklevel=2
+            )
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator
+
+
+deprec_get_idx = deprecated(
+    "get_idx() is deprecated and will be removed in a future version. Please use get_all_idxes() instead.")

ams/utils/paths.py

@@ -0,0 +1,257 @@
+"""
+Utility functions for loading ams stock test cases,
+mainly revised from ``andes.utils.paths``.
+"""
+import logging
+import os
+import pathlib
+import tempfile
+
+logger = logging.getLogger(__name__)
+
+
+class DisplayablePath:
+    display_filename_prefix_middle = '├──'
+    display_filename_prefix_last = '└──'
+    display_parent_prefix_middle = '    '
+    display_parent_prefix_last = '│   '
+
+    def __init__(self, path, parent_path, is_last):
+        self.path = pathlib.Path(str(path))
+        self.parent = parent_path
+        self.is_last = is_last
+        if self.parent:
+            self.depth = self.parent.depth + 1
+        else:
+            self.depth = 0
+
+    @property
+    def displayname(self):
+        if self.path.is_dir():
+            return self.path.name + '/'
+        return self.path.name
+
+    @classmethod
+    def make_tree(cls, root, parent=None, is_last=False, criteria=None):
+        root = pathlib.Path(str(root))
+        criteria = criteria or cls._default_criteria
+
+        displayable_root = cls(root, parent, is_last)
+        yield displayable_root
+
+        children = sorted(list(path
+                               for path in root.iterdir()
+                               if criteria(path)),
+                          key=lambda s: str(s).lower())
+        count = 1
+        for path in children:
+            is_last = count == len(children)
+            if path.is_dir():
+                yield from cls.make_tree(path,
+                                         parent=displayable_root,
+                                         is_last=is_last,
+                                         criteria=criteria)
+            else:
+                yield cls(path, displayable_root, is_last)
+            count += 1
+
+    @classmethod
+    def _default_criteria(cls, path):
+        return True
+
+    def displayable(self):
+        if self.parent is None:
+            return self.displayname
+
+        _filename_prefix = (self.display_filename_prefix_last
+                            if self.is_last
+                            else self.display_filename_prefix_middle)
+
+        parts = ['{!s} {!s}'.format(_filename_prefix,
+                                    self.displayname)]
+
+        parent = self.parent
+        while parent and parent.parent is not None:
+            parts.append(self.display_parent_prefix_middle
+                         if parent.is_last
+                         else self.display_parent_prefix_last)
+            parent = parent.parent
+
+        return ''.join(reversed(parts))
+
+
+def ams_root():
+    """
+    Return the root path to the ams source code.
+    """
+
+    dir_name = os.path.dirname(os.path.abspath(__file__))
+    return os.path.normpath(os.path.join(dir_name, '..'))
+
+
+def cases_root():
+    """
+    Return the root path to the stock cases
+    """
+
+    dir_name = os.path.dirname(os.path.abspath(__file__))
+    return os.path.normpath(os.path.join(dir_name, '..', 'cases'))
+
+
+def tests_root():
+    """Return the root path to the stock cases"""
+    dir_name = os.path.dirname(os.path.abspath(__file__))
+    return os.path.normpath(os.path.join(dir_name, '..', '..', 'tests'))
+
+
+def get_case(rpath, check=True):
+    """
+    Return the path to a stock case for a given path relative to ``ams/cases``.
+
+    To list all cases, use ``ams.list_cases()``.
+
+    Parameters
+    ----------
+    check : bool
+        True to check if file exists
+
+    Examples
+    --------
+    To get the path to the case `kundur_full.xlsx` under folder `kundur`, do ::
+
+        ams.get_case('kundur/kundur_full.xlsx')
+
+    """
+    case_path = os.path.join(cases_root(), rpath)
+    case_path = os.path.normpath(case_path)
+
+    if check is True and (not os.path.isfile(case_path)):
+        raise FileNotFoundError(f'"{rpath}" is not a valid relative path to a stock case.')
+    return case_path
+
+
+def list_cases(rpath='.', no_print=False):
+    """
+    List stock cases under a given folder relative to ``ams/cases``
+    """
+    case_path = os.path.join(cases_root(), rpath)
+    case_path = os.path.normpath(case_path)
+
+    tree = DisplayablePath.make_tree(pathlib.Path(case_path))
+    out = []
+    for path in tree:
+        out.append(path.displayable())
+
+    out = '\n'.join(out)
+    if no_print is False:
+        print(out)
+    else:
+        return out
+
+
+def get_config_path(file_name='ams.rc'):
+    """
+    Return the path of the config file to be loaded.
+
+    Search Priority: 1. current directory; 2. home directory.
+
+    Parameters
+    ----------
+    file_name : str, optional
+        Config file name with the default as ``ams.rc``.
+
+    Returns
+    -------
+    Config path in string if found; None otherwise.
+    """
+
+    conf_path = None
+    home_dir = os.path.expanduser('~')
+
+    # test ./ams.conf
+    if os.path.isfile(file_name):
+        conf_path = file_name
+    # test ~/ams.conf
+    elif os.path.isfile(os.path.join(home_dir, '.ams', file_name)):
+        conf_path = os.path.join(home_dir, '.ams', file_name)
+
+    return conf_path
+
+
+def get_pycode_path(pycode_path=None, mkdir=False):
+    """
+    Get the path to the ``pycode`` folder.
+    """
+
+    if pycode_path is None:
+        pycode_path = os.path.join(get_dot_andes_path(), 'pycode')
+
+    if mkdir is True:
+        os.makedirs(pycode_path, exist_ok=True)
+
+    return pycode_path
+
+
+def get_pkl_path():
+    """
+    Get the path to the picked/dilled function calls.
+
+    Returns
+    -------
+    str
+        Path to the calls.pkl file
+
+    """
+    pkl_name = 'calls.pkl'
+    ams_path = get_dot_andes_path()
+
+    if not os.path.exists(ams_path):
+        os.makedirs(ams_path)
+
+    pkl_path = os.path.join(ams_path, pkl_name)
+
+    return pkl_path
+
+
+def get_dot_andes_path():
+    """
+    Return the path to ``$HOME/.ams``
+    """
+
+    return os.path.join(str(pathlib.Path.home()), '.ams')
+
+
+def get_log_dir():
+    """
+    Get the directory for log file.
+
+    The default is ``<tempdir>/ams``, where ``<tempdir>`` is provided by ``tempfile.gettempdir()``.
+
+    Returns
+    -------
+    str
+        The path to the temporary logging directory
+    """
+    tempdir = tempfile.gettempdir()
+    path = tempfile.mkdtemp(prefix='ams-', dir=tempdir)
+    return path
+
+
+def confirm_overwrite(outfile, overwrite=None):
+    """
+    Confirm overwriting a file.
+    """
+
+    try:
+        if os.path.isfile(outfile):
+            if overwrite is None:
+                choice = input(f'File "{outfile}" already exist. Overwrite? [y/N]').lower()
+                if len(choice) == 0 or choice[0] != 'y':
+                    logger.warning(f'File "{outfile}" not overwritten.')
+                    return False
+            elif overwrite is False:
+                return False
+    except TypeError:
+        pass
+
+    return True

docs/Makefile

@@ -0,0 +1,21 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    =  "-W"  # This flag turns warnings into errors.
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = PackagingScientificPython
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/_generated/_generated/ams.core.model.Model.alter.rst

@@ -0,0 +1,6 @@
+Model.alter
+===========
+
+.. currentmodule:: ams.core.model
+
+.. automethod:: Model.alter

docs/source/_generated/_generated/ams.core.model.Model.class_name.rst

@@ -0,0 +1,6 @@
+Model.class\_name
+=================
+
+.. currentmodule:: ams.core.model
+
+.. autoproperty:: Model.class_name

docs/source/_generated/_generated/ams.core.model.Model.doc.rst

@@ -0,0 +1,6 @@
+Model.doc
+=========
+
+.. currentmodule:: ams.core.model
+
+.. automethod:: Model.doc

docs/source/_generated/_generated/ams.core.model.Model.get.rst

@@ -0,0 +1,6 @@
+Model.get
+=========
+
+.. currentmodule:: ams.core.model
+
+.. automethod:: Model.get

docs/source/_generated/_generated/ams.core.model.Model.get_idx.rst

@@ -0,0 +1,6 @@
+Model.get\_idx
+==============
+
+.. currentmodule:: ams.core.model
+
+.. automethod:: Model.get_idx

docs/source/_generated/_generated/ams.core.model.Model.idx2uid.rst

@@ -0,0 +1,6 @@
+Model.idx2uid
+=============
+
+.. currentmodule:: ams.core.model
+
+.. automethod:: Model.idx2uid

docs/source/_generated/_generated/ams.core.model.Model.list2array.rst

@@ -0,0 +1,6 @@
+Model.list2array
+================
+
+.. currentmodule:: ams.core.model
+
+.. automethod:: Model.list2array

docs/source/_generated/_generated/ams.core.model.Model.set.rst

@@ -0,0 +1,6 @@
+Model.set
+=========
+
+.. currentmodule:: ams.core.model
+
+.. automethod:: Model.set

docs/source/_generated/_generated/ams.core.model.Model.set_backref.rst

@@ -0,0 +1,6 @@
+Model.set\_backref
+==================
+
+.. currentmodule:: ams.core.model
+
+.. automethod:: Model.set_backref

docs/source/_generated/_generated/ams.core.param.RParam.class_name.rst

@@ -0,0 +1,6 @@
+RParam.class\_name
+==================
+
+.. currentmodule:: ams.core.param
+
+.. autoproperty:: RParam.class_name

docs/source/_generated/_generated/ams.core.param.RParam.dtype.rst

@@ -0,0 +1,6 @@
+RParam.dtype
+============
+
+.. currentmodule:: ams.core.param
+
+.. autoproperty:: RParam.dtype

docs/source/_generated/_generated/ams.core.param.RParam.evaluate.rst

@@ -0,0 +1,6 @@
+RParam.evaluate
+===============
+
+.. currentmodule:: ams.core.param
+
+.. automethod:: RParam.evaluate

docs/source/_generated/_generated/ams.core.param.RParam.get_idx.rst

@@ -0,0 +1,6 @@
+RParam.get\_idx
+===============
+
+.. currentmodule:: ams.core.param
+
+.. automethod:: RParam.get_idx

docs/source/_generated/_generated/ams.core.param.RParam.n.rst

@@ -0,0 +1,6 @@
+RParam.n
+========
+
+.. currentmodule:: ams.core.param
+
+.. autoproperty:: RParam.n

docs/source/_generated/_generated/ams.core.param.RParam.parse.rst

@@ -0,0 +1,6 @@
+RParam.parse
+============
+
+.. currentmodule:: ams.core.param
+
+.. automethod:: RParam.parse

docs/source/_generated/_generated/ams.core.param.RParam.shape.rst

@@ -0,0 +1,6 @@
+RParam.shape
+============
+
+.. currentmodule:: ams.core.param
+
+.. autoproperty:: RParam.shape

docs/source/_generated/_generated/ams.core.param.RParam.size.rst

@@ -0,0 +1,6 @@
+RParam.size
+===========
+
+.. currentmodule:: ams.core.param
+
+.. autoproperty:: RParam.size

docs/source/_generated/_generated/ams.core.param.RParam.update.rst

@@ -0,0 +1,6 @@
+RParam.update
+=============
+
+.. currentmodule:: ams.core.param
+
+.. automethod:: RParam.update

docs/source/_generated/_generated/ams.core.param.RParam.v.rst

@@ -0,0 +1,6 @@
+RParam.v
+========
+
+.. currentmodule:: ams.core.param
+
+.. autoproperty:: RParam.v

docs/source/_generated/_generated/ams.core.service.LoadScale.assign_memory.rst

@@ -0,0 +1,6 @@
+LoadScale.assign\_memory
+========================
+
+.. currentmodule:: ams.core.service
+
+.. automethod:: LoadScale.assign_memory

docs/source/_generated/_generated/ams.core.service.LoadScale.class_name.rst

@@ -0,0 +1,6 @@
+LoadScale.class\_name
+=====================
+
+.. currentmodule:: ams.core.service
+
+.. autoproperty:: LoadScale.class_name

docs/source/_generated/_generated/ams.core.service.LoadScale.evaluate.rst

@@ -0,0 +1,6 @@
+LoadScale.evaluate
+==================
+
+.. currentmodule:: ams.core.service
+
+.. automethod:: LoadScale.evaluate

docs/source/_generated/_generated/ams.core.service.LoadScale.get_names.rst

@@ -0,0 +1,6 @@
+LoadScale.get\_names
+====================
+
+.. currentmodule:: ams.core.service
+
+.. automethod:: LoadScale.get_names

docs/source/_generated/_generated/ams.core.service.LoadScale.n.rst

@@ -0,0 +1,6 @@
+LoadScale.n
+===========
+
+.. currentmodule:: ams.core.service
+
+.. autoproperty:: LoadScale.n

docs/source/_generated/_generated/ams.core.service.LoadScale.parse.rst

@@ -0,0 +1,6 @@
+LoadScale.parse
+===============
+
+.. currentmodule:: ams.core.service
+
+.. automethod:: LoadScale.parse

docs/source/_generated/_generated/ams.core.service.LoadScale.shape.rst

@@ -0,0 +1,6 @@
+LoadScale.shape
+===============
+
+.. currentmodule:: ams.core.service
+
+.. autoproperty:: LoadScale.shape

docs/source/_generated/_generated/ams.core.service.LoadScale.size.rst

@@ -0,0 +1,6 @@
+LoadScale.size
+==============
+
+.. currentmodule:: ams.core.service
+
+.. autoproperty:: LoadScale.size

docs/source/_generated/_generated/ams.core.service.LoadScale.update.rst

@@ -0,0 +1,6 @@
+LoadScale.update
+================
+
+.. currentmodule:: ams.core.service
+
+.. automethod:: LoadScale.update

docs/source/_generated/_generated/ams.core.service.LoadScale.v.rst

@@ -0,0 +1,6 @@
+LoadScale.v
+===========
+
+.. currentmodule:: ams.core.service
+
+.. autoproperty:: LoadScale.v

docs/source/_generated/_generated/ams.core.service.MinDur.assign_memory.rst

@@ -0,0 +1,6 @@
+MinDur.assign\_memory
+=====================
+
+.. currentmodule:: ams.core.service
+
+.. automethod:: MinDur.assign_memory

docs/source/_generated/_generated/ams.core.service.MinDur.class_name.rst

@@ -0,0 +1,6 @@
+MinDur.class\_name
+==================
+
+.. currentmodule:: ams.core.service
+
+.. autoproperty:: MinDur.class_name

docs/source/_generated/_generated/ams.core.service.MinDur.evaluate.rst

@@ -0,0 +1,6 @@
+MinDur.evaluate
+===============
+
+.. currentmodule:: ams.core.service
+
+.. automethod:: MinDur.evaluate

docs/source/_generated/_generated/ams.core.service.MinDur.get_names.rst

@@ -0,0 +1,6 @@
+MinDur.get\_names
+=================
+
+.. currentmodule:: ams.core.service
+
+.. automethod:: MinDur.get_names