ltbams 0.9.9__py3-none-any.whl → 1.0.2a1__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/_templates/autosummary/base.rst

@@ -0,0 +1,5 @@
+{{ objname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

docs/source/_templates/autosummary/class.rst

@@ -0,0 +1,35 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :toctree: _generated/
+
+   {% for item in methods %}
+       {% if item != "__init__" %}
+          ~{{ name }}.{{ item }}
+       {% endif %}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+      :toctree: _generated/
+
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/source/_templates/autosummary/module.rst

@@ -0,0 +1,65 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module Attributes
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+
+.. autosummary::
+   :recursive:
+
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/source/_templates/autosummary/module_toctree.rst

@@ -0,0 +1,66 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module Attributes
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+
+.. autosummary::
+   :recursive:
+   :toctree:
+
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/source/api.rst

@@ -0,0 +1,102 @@
+.. _api_reference:
+
+=============
+API reference
+=============
+
+
+System
+======
+
+.. autosummary::
+   :maxdepth:4
+   :recursive:
+   :toctree: _generated
+   :caption: System
+   :template: autosummary/module_toctree.rst
+
+   ams.system
+
+
+Model
+======
+
+.. autosummary::
+   :maxdepth:4
+   :recursive:
+   :toctree: _generated
+   :caption: Model
+   :template: autosummary/module_toctree.rst
+
+   ams.core.model
+   ams.core.param
+   ams.core.service
+
+
+Routines
+========
+
+.. autosummary::
+   :maxdepth:4
+   :recursive:
+   :toctree: _generated
+   :caption: Routines
+   :template: autosummary/module_toctree.rst
+
+   ams.routines.routine
+   ams.routines.dcopf
+   ams.routines.pflow
+
+
+Optimization
+=============
+
+.. autosummary::
+   :maxdepth:4
+   :recursive:
+   :toctree: _generated
+   :caption: Optimization
+   :template: autosummary/module_toctree.rst
+
+   ams.opt
+
+
+I/O
+===
+
+.. autosummary::
+   :maxdepth:4
+   :toctree: _generated
+   :recursive:
+   :caption: I/O
+   :template: autosummary/module_toctree.rst
+
+   ams.io
+
+
+Interoperability
+================
+
+.. autosummary::
+   :maxdepth:4
+   :toctree: _generated
+   :recursive:
+   :caption: Interoperability
+   :template: autosummary/module_toctree.rst
+
+   ams.interface
+
+
+Others
+======
+
+.. autosummary::
+   :maxdepth:4
+   :toctree: _generated
+   :recursive:
+   :caption: Others
+   :template: autosummary/module_toctree.rst
+
+   ams.cli
+   ams.main
+   ams.utils.paths