peslite-core 0.5.0__py3-none-any.whl

peslite/__init__.py

@@ -0,0 +1,42 @@
+"""Power-electronics converter simulation on a port-Hamiltonian model kernel.
+
+The package has five parts: :mod:`.components` (power circuit and converter hardware),
+:mod:`.control` (the converter's controller), :mod:`.assembly` (a system built from a simulation
+file), :mod:`.solver` (the model kernel, integrators and run), and :mod:`.addons` (custom extension
+entry points and optional functions). Plant quantities are in SI; controllers work in each unit's
+pu bases.
+"""
+
+from . import solver, control, components, assembly
+from .solver import (AdaptiveSolver, BlackBoxSubsystem, DormandPrince45, FixedStepSolver, Model,
+                     MultirateSolver, make_solver)
+from .control import OutputStage, VSCController, make_controller, register_loop_type
+from .components import (ADC, ADCSample, PWM, PWMAveragingModel, ZOH, AveragingModel, SwitchingModel,
+                         ThreePhaseBridge, CarrierComparison, FullBridge, HalfBridge,
+                         MeasurementPorts, make_bridge,
+                         make_modulator, register_component_type)
+from .assembly import (DCConverter, Params, Protection, ProtectionSample,
+                       SourceScenario, System, Unit, VSC,
+                       dump, dumps, load, register_event_type)
+from .solver.simulation import Simulation, SimulationResult, main
+from .assembly.exporter import ExportResult, export
+from . import addons
+from .assembly.params import _register_load_preparer
+
+_register_load_preparer(addons._discover_for)
+
+__version__ = "0.5.0"
+
+__all__ = [
+    "solver", "control", "components", "assembly", "addons",
+    "Params", "load", "dump", "dumps", "System", "Unit", "VSC",
+    "DCConverter", "Protection", "ProtectionSample", "MeasurementPorts", "Model", "BlackBoxSubsystem",
+    "SourceScenario",
+    "Simulation", "SimulationResult", "ExportResult", "export", "VSCController", "main", "make_controller", "make_modulator", "make_solver",
+    "register_loop_type", "register_component_type", "register_event_type",
+    "OutputStage", "ADC", "ADCSample", "PWM", "SwitchingModel", "PWMAveragingModel", "AveragingModel",
+    "ThreePhaseBridge", "make_bridge",
+    "HalfBridge", "FullBridge",
+    "CarrierComparison", "ZOH",
+    "FixedStepSolver", "AdaptiveSolver", "DormandPrince45", "MultirateSolver", "__version__",
+]

peslite/addons/__init__.py

@@ -0,0 +1,75 @@
+"""Optional functions and automatically discovered custom PESLite types."""
+
+from __future__ import annotations
+
+from importlib import import_module, invalidate_caches
+from pathlib import Path
+from typing import Any
+
+from . import components, control
+from ._discovery import discover_modules
+
+# These imports happen once when PESLite starts.  They populate the existing registries; no
+# directory search or add-on dispatch remains in the simulation hot path.
+control.discover()
+components.discover()
+
+__all__ = ["control", "components", "functions", "energy_closure", "plot_csv", "plot_result"]
+
+
+def _merge_path(package, directory: Path) -> bool:
+    """Append one real directory to a package search path, once."""
+    if not directory.is_dir():
+        return False
+    resolved = str(directory.resolve())
+    if resolved not in package.__path__:
+        package.__path__.append(resolved)
+    return True
+
+
+def _discover_for(simulation_file: str | Path) -> tuple[Any, ...]:
+    """Merge and discover ``PESaddons`` beside one simulation file.
+
+    The installed add-on packages remain the first search locations.  A sibling ``PESaddons``
+    contributes the same ``control``, ``components`` and ``functions`` package paths without
+    changing the process-wide ``sys.path``.  Controller and component decorators must run before
+    the simulation file is parsed; functions remain lazy and are imported only when requested.
+    """
+    root = Path(simulation_file).resolve().parent / "PESaddons"
+    if not root.is_dir():
+        return ()
+
+    _merge_path(import_module(__name__), root)
+    locations = []
+    for package, name in ((control, "control"), (components, "components")):
+        directory = root / name
+        if _merge_path(package, directory):
+            locations.append((package, directory))
+
+    # Import the existing functions package only when this project contributes that namespace.
+    # Optional third-party implementations remain lazy; this merely makes project-local function
+    # modules importable from the same path.
+    function_directory = root / "functions"
+    if function_directory.is_dir():
+        functions = import_module(f"{__name__}.functions")
+        _merge_path(functions, function_directory)
+    invalidate_caches()
+
+    imported = []
+    for package, directory in locations:
+        imported.extend(discover_modules(package.__name__, (str(directory),)))
+    return tuple(imported)
+
+
+def __getattr__(name: str) -> Any:
+    """Load optional function implementations only when their API is requested."""
+    if name == "functions":
+        module = import_module(f"{__name__}.functions")
+        globals()[name] = module
+        return module
+    if name in {"energy_closure", "plot_csv", "plot_result"}:
+        module = import_module(f"{__name__}.functions")
+        globals().update({public: getattr(module, public)
+                          for public in ("energy_closure", "plot_csv", "plot_result")})
+        return globals()[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

peslite/addons/_discovery.py

@@ -0,0 +1,19 @@
+"""Import modules placed in one add-on search package."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from pkgutil import iter_modules
+from types import ModuleType
+from typing import Iterable
+
+
+def discover_modules(package: str, paths: Iterable[str]) -> tuple[ModuleType, ...]:
+    """Import every module directly contained in ``paths`` in deterministic order.
+
+    Importing a controller or component module executes its normal PESLite registration
+    decorators.  Python's module cache makes repeated discovery safe and inexpensive.
+    """
+    prefix = f"{package}."
+    names = sorted(info.name for info in iter_modules(paths, prefix))
+    return tuple(import_module(name) for name in names)

peslite/addons/components/__init__.py

@@ -0,0 +1,22 @@
+"""Entry point for optional and custom PESLite component modules.
+
+Place modules in this package and register their parameter dataclasses with
+``register_component_type``. PESLite imports each module during package initialisation, so its
+types enter the same registry and configuration search path as built-in circuit elements.
+"""
+
+from __future__ import annotations
+
+from types import ModuleType
+
+from ... import components as _components
+from .._discovery import discover_modules
+
+# Add-on components use the exact public component API and the exact built-in element registry.
+globals().update({name: getattr(_components, name) for name in _components.__all__})
+__all__ = [*_components.__all__, "discover"]
+
+
+def discover() -> tuple[ModuleType, ...]:
+    """Import component add-ons found on this package's search path."""
+    return discover_modules(__name__, __path__)

peslite/addons/control/__init__.py

@@ -0,0 +1,23 @@
+"""Entry point for optional and custom PESLite control-loop modules.
+
+Place modules in this package and register their loop classes with
+``register_loop_type``. PESLite imports each module during package initialisation, so its types
+enter the same registry and configuration search path as built-in control loops.
+"""
+
+from __future__ import annotations
+
+from types import ModuleType
+
+from ... import control as _control
+from .._discovery import discover_modules
+
+# An add-on control module gets the same public construction surface as a built-in control module.
+# Keeping this list tied to ``control.__all__`` prevents the two entry points drifting.
+globals().update({name: getattr(_control, name) for name in _control.__all__})
+__all__ = [*_control.__all__, "discover"]
+
+
+def discover() -> tuple[ModuleType, ...]:
+    """Import control add-ons found on this package's search path."""
+    return discover_modules(__name__, __path__)

peslite/addons/functions/__init__.py

@@ -0,0 +1,20 @@
+"""Standard namespace for lazily loaded built-in and project-local functions."""
+
+from importlib import import_module
+
+_EXPORTS = {
+    "energy_closure": ("energy_audit", "energy_closure"),
+    "plot_csv": ("plotting", "plot_csv"),
+    "plot_result": ("plotting", "plot_result"),
+}
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name):
+    """Load a public function from its implementation module when requested."""
+    if name not in _EXPORTS:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module_name, attribute = _EXPORTS[name]
+    value = getattr(import_module(f"{__name__}.{module_name}"), attribute)
+    globals()[name] = value
+    return value

peslite/assembly/__init__.py

@@ -0,0 +1,76 @@
+"""Assembly of a system from a simulation file.
+
+``params``: the file parameters, including runtime changes; ``validate``: cross-section checks;
+``events``: event types and scenarios; ``protection``: the unified protection subsystem;
+``unit``: a converter unit; ``system``: the network, registered elements and event operations as
+one model.
+"""
+
+from .params import (BaseValues, ConfigError, ControlParams, LCCLinkParams, LCCSLinkParams,
+                     MultiSSLinkParams, Params, SCCParams, SSLinkParams, UnitParams,
+                     dump, dumps, from_dict, load,
+                     read_initial, to_dict)
+from .events import (EVENT_TYPES, Event, Scenario, SourceScenario,
+                     register_event_type)
+from .protection import Protection, ProtectionSample
+from .unit import DCConverter, Unit, VSC
+from .system import System
+from .params import _DCConverterUnitFields, _VSCUnitFields, _WPTUnitFields
+from .system import _assemble_dc_converter, _assemble_vsc, _assemble_wpt
+from .types import register_unit_type
+from .validate import _dc_converter, _unit, _wpt
+from ..control.profiles import control_type
+from . import circuit as _circuit
+from ..solver.netlist import _install_device_runtime
+
+_install_device_runtime(_circuit.STANDALONE_RUNTIME)
+
+register_unit_type(
+    "vsc",
+    params=_VSCUnitFields,
+    default_bridge="three_phase_bridge",
+    default_port="dc",
+    ports=("dc", "power"),
+    phases=3,
+    bridge_types=frozenset(("three_phase_bridge",)),
+    measurement_channels=frozenset(("u_g", "i_c", "u_dc")),
+    current_channel="i_c",
+    protection_criteria=frozenset((
+        "overcurrent", "rms_current", "undervoltage", "overvoltage", "frequency", "dc_voltage", "rocof",
+    )),
+    defaults_grid_frequency=True,
+    validator=_unit,
+    assembler=_assemble_vsc,
+)
+register_unit_type(
+    "dc_converter",
+    params=_DCConverterUnitFields,
+    default_bridge=lambda control: control_type(control.type).default_bridge,
+    default_port="dc",
+    ports=("dc", "power"),
+    phases=1,
+    bridge_types=frozenset(("half_bridge", "full_bridge")),
+    measurement_channels=frozenset(("current", "voltage", "vin", "power")),
+    current_channel="current",
+    protection_criteria=frozenset((
+        "overcurrent", "rms_current", "undervoltage", "overvoltage", "dc_voltage",
+    )),
+    validator=_dc_converter,
+    assembler=_assemble_dc_converter,
+)
+register_unit_type(
+    "wpt",
+    params=_WPTUnitFields,
+    children=("primary", "secondary"),
+    default_port="primary",
+    phases=1,
+    validator=_wpt,
+    assembler=_assemble_wpt,
+)
+
+__all__ = ["Params", "BaseValues", "ConfigError", "load", "dump", "dumps", "from_dict", "to_dict", "read_initial",
+           "Event", "EVENT_TYPES", "register_event_type", "Scenario",
+           "SourceScenario", "Protection", "ProtectionSample", "Unit", "VSC", "DCConverter",
+           "UnitParams", "ControlParams",
+           "SSLinkParams", "LCCLinkParams", "LCCSLinkParams", "MultiSSLinkParams", "SCCParams",
+           "System"]