libecalc 8.19.0__py3-none-any.whl

ecalc_cli/README.md

@@ -0,0 +1,14 @@
+# eCalc CLI
+
+eCalc CLI is provided as a part of the libeCalc package as an example UI for how to use libeCalc, AND for a more
+convenient way to use libeCalc without needing to have knowledge about programming.
+
+eCalc CLI is implemented with Typer, that provides helpful interactive help on how to use it.
+
+Start with
+
+```shell
+ecalc --help
+```
+
+and go on from there.

ecalc_cli/commands/run.py

@@ -0,0 +1,222 @@
+from datetime import datetime
+from pathlib import Path
+
+import libecalc.common.time_utils
+import libecalc.version
+import typer
+from libecalc.application.energy_calculator import EnergyCalculator
+from libecalc.application.graph_result import GraphResult
+from libecalc.common.math.numbers import Numbers
+from libecalc.common.run_info import RunInfo
+from libecalc.infrastructure.file_utils import OutputFormat, get_result_output
+from libecalc.presentation.json_result.mapper import get_asset_result
+from libecalc.presentation.yaml.model import YamlModel
+
+from ecalc_cli.errors import EcalcCLIError
+from ecalc_cli.io.cache import Cache
+from ecalc_cli.io.output import (
+    write_flow_diagram,
+    write_json,
+    write_ltp_export,
+    write_output,
+    write_stp_export,
+)
+from ecalc_cli.logger import logger
+from ecalc_cli.types import DateFormat, Frequency
+
+
+def run(
+    model_file: Path = typer.Argument(
+        ...,
+        help="The Model YAML-file specifying time series inputs,"
+        " facility inputs and the relationship between energy consumers.",
+    ),
+    output_frequency: Frequency = typer.Option(
+        libecalc.common.time_utils.Frequency.NONE.name,
+        "--output-frequency",
+        "-f",
+        "--outputfrequency",
+        help="Frequency of output. Options are DAY, MONTH, YEAR. If not specified, it will give"
+        " time steps equal to the union of all input given with INFLUENCE_TIME_VECTOR set to True."
+        " Down-sampling the result may lead to loss of data, and rates such as MW may not add up to cumulative values",
+    ),
+    csv: bool = typer.Option(
+        True,
+        "--csv",
+        "-c",
+        help="Toggle output of csv data.",
+    ),
+    json: bool = typer.Option(
+        False,
+        "--json",
+        help="Toggle output of json output.",
+    ),
+    output_folder: Path = typer.Option(
+        None,
+        "--output-folder",
+        "-o",
+        "--outputfolder",
+        help="Outputfolder. Defaults to output/ relative to the yml setup file",
+        show_default=False,
+    ),
+    name_prefix: str = typer.Option(
+        None,
+        "--name-prefix",
+        "-n",
+        "--nameprefix",
+        help="Name prefix for output data. Defaults to name of setup file.",
+    ),
+    ltp_export: bool = typer.Option(
+        False,
+        "--ltp-export",
+        help="In addition to standard output, a specific Long Term Prognosis (LTP) file "
+        "will be provided for simple export of LTP relevant data (Tabular Separated Values).",
+    ),
+    stp_export: bool = typer.Option(
+        False,
+        "--stp-export",
+        help="In addition to standard output, a specific Short Term Prognosis (STP) file "
+        "will be provided for simple export of STP relevant data (Tabular Separated Values).",
+    ),
+    flow_diagram: bool = typer.Option(
+        False,
+        "--flow-diagram",
+        help="Output the input model formatted to be displayed in a custom flow diagram format in JSON",
+    ),
+    detailed_output: bool = typer.Option(
+        False,
+        "--detailed-output",
+        "--detailedoutput",
+        help="Output detailed output."
+        " When False you will get basic results such as energy usage, power, time vector.",
+    ),
+    date_format_option: DateFormat = typer.Option(
+        DateFormat.ISO_8601.value,
+        "--date-format-option",
+        help='Date format option. 0: "YYYY-MM-DD HH:MM:SS" (Accepted variant of ISO8601), 1: "YYYYMMDD HH:MM:SS" (ISO8601), 2: "DD.MM.YYYY HH:MM:SS". Default 0 (ISO 8601)',
+    ),
+):
+    """CLI command to run a ecalc model."""
+    if output_folder is None:
+        output_folder = model_file.parent / "output"
+
+    if name_prefix is None:
+        name_prefix = model_file.stem
+
+    output_frequency = libecalc.common.time_utils.Frequency[output_frequency.name]
+
+    run_info = RunInfo(version=libecalc.version.current_version(), start=datetime.now())
+    logger.info(f"eCalc™ simulation starting. Running {run_info}")
+    validate_arguments(model_file=model_file, output_folder=output_folder)
+
+    model = YamlModel(path=model_file, output_frequency=output_frequency)
+
+    if (flow_diagram or ltp_export) and (model.start is None or model.end is None):
+        logger.warning(
+            "When using Flow Diagram or Long Term Prognosis export, START and END should be specified in YAML to make sure you get the intended period as output. See documentation for more information."
+        )
+
+    if flow_diagram:
+        write_flow_diagram(
+            model_dto=model.dto,
+            result_options=model.result_options,
+            output_folder=output_folder,
+            name_prefix=name_prefix,
+        )
+
+    energy_calculator = EnergyCalculator(graph=model.graph)
+    precision = 6
+    consumer_results = energy_calculator.evaluate_energy_usage(model.variables)
+    emission_results = energy_calculator.evaluate_emissions(
+        variables_map=model.variables,
+        consumer_results=consumer_results,
+    )
+    results_core = GraphResult(
+        graph=model.graph,
+        consumer_results=consumer_results,
+        variables_map=model.variables,
+        emission_results=emission_results,
+    )
+
+    run_info.end = datetime.now()
+
+    cache = Cache(user_specified_output_path=output_folder)
+    cache.write_run_info(run_info)
+    cache.write_results(
+        results=results_core,
+        component_dto=model.dto,
+    )
+
+    output_prefix: Path = output_folder / name_prefix
+
+    results_dto = get_asset_result(results_core)
+
+    if output_frequency != Frequency.NONE:
+        # Note: LTP can't use this resampled-result yet, because of differences in methodology.
+        results_resampled = Numbers.format_results_to_precision(
+            results_dto.resample(output_frequency), precision=precision
+        )
+    else:
+        results_resampled = results_dto.model_copy()
+
+    if csv:
+        csv_data = get_result_output(
+            results=results_resampled,
+            output_format=OutputFormat.CSV,
+            simple_output=not detailed_output,
+            date_format_option=int(date_format_option.value),
+        )
+        write_output(output=csv_data, output_file=output_prefix.with_suffix(".csv"))
+
+    if json:
+        write_json(
+            results=results_resampled,
+            output_folder=output_folder,
+            name_prefix=name_prefix,
+            run_info=run_info,
+            date_format_option=int(date_format_option.value),
+            simple_output=not detailed_output,
+        )
+
+    if ltp_export:
+        write_ltp_export(
+            results=results_core,
+            output_folder=output_folder,
+            frequency=output_frequency,  # Keep until alternative export option is in place (e.g. stp-export)
+            name_prefix=name_prefix,
+        )
+
+    if stp_export:
+        write_stp_export(
+            results=results_core,
+            output_folder=output_folder,
+            frequency=output_frequency,  # Keep until alternative export option is in place (e.g. stp-export)
+            name_prefix=name_prefix,
+        )
+
+    logger.info(f"eCalc™ simulation successful. Duration: {run_info.end - run_info.start}")
+
+
+def validate_arguments(model_file: Path, output_folder: Path):
+    """Helper function used to validate the CLI run command arguments.
+
+    Args:
+        model_file:
+        output_folder:
+
+    Returns:
+
+    Raises:
+        EcalcCLIError: If one of the arguments are invalid
+
+    """
+    if not model_file.is_file():
+        raise EcalcCLIError(f"Setup file: {model_file.absolute()}: no such file")
+
+    if not output_folder.parent.is_dir():
+        raise EcalcCLIError(
+            f"Output path {output_folder} not valid. Please specify an existing path or the name of a new folder in an existing path"
+        )
+
+    if not output_folder.is_dir():
+        output_folder.mkdir()

ecalc_cli/commands/selftest.py

@@ -0,0 +1,38 @@
+import libecalc.version
+from ecalc_neqsim_wrapper import start_server
+
+from ecalc_cli.logger import logger
+
+
+def selftest_java() -> bool:
+    """Check java installation.
+
+    Returns:
+        bool: True if Java is installed correctly, False otherwise.
+
+    """
+    try:
+        start_server()
+        logger.debug("SUCCESS: Java seems to be correctly installed!")
+        return True
+    except Exception:
+        logger.error(
+            "Java does not seem to be installed. eCalc will currently not work since NeqSim depends on Java. Please install. See instructions in documentation."
+        )
+        return False
+
+
+def selftest():
+    """Did eCalc install successfully? Go through a number of checkpoints and let user know what is ok and what is not."""
+    logger.info(f"eCalc™ Version {libecalc.version.current_version()}")
+    logger.info("Starting selftest ...")
+
+    # 1. Check that Java is installed (required for NeqSim and fluid simulation), and Neqsim can be used
+    java_installed = selftest_java()
+
+    # TODO: 3. Run the simple test fixture, see that it works (1. from code 2. from yaml)
+
+    if java_installed:
+        logger.info("eCalc™ selftest done successfully.")
+    else:
+        logger.error("eCalc™ selftest done with errors. See descriptions above.")

ecalc_cli/commands/show.py

@@ -0,0 +1,120 @@
+from pathlib import Path
+
+import libecalc.common.time_utils
+import libecalc.version
+import typer
+from libecalc.infrastructure.file_utils import (
+    OutputFormat,
+    get_component_output,
+    get_result_output,
+)
+from libecalc.presentation.yaml.yaml_entities import ResourceStream
+from libecalc.presentation.yaml.yaml_models.pyyaml_yaml_model import PyYamlYamlModel
+
+from ecalc_cli.io.cache import Cache
+from ecalc_cli.io.output import write_output
+from ecalc_cli.logger import logger
+from ecalc_cli.types import DateFormat, Frequency
+
+app = typer.Typer()
+
+
+@app.command("yaml")
+def show_yaml(
+    model_file: Path = typer.Argument(
+        ...,
+        help="YAML file specifying time series inputs, facility inputs and the relationship between energy consumers.",
+    ),
+    output_file: Path = typer.Option(
+        None,
+        "--file",
+        help="Write the data to a file with the specified name.",
+    ),
+):
+    """Show yaml model. This will show the yaml after processing !include."""
+    model_filepath = model_file
+    with open(model_filepath) as model_file:
+        read_model = PyYamlYamlModel.dump_and_load_yaml(
+            ResourceStream(name=model_file.name, stream=model_file), base_dir=model_filepath.parent
+        )
+        write_output(read_model, output_file)
+
+
+@app.command("results")
+def show_results(
+    component_name: str = typer.Option(
+        None,
+        "-n",
+        "--name",
+        help="Filter the results to only show the component with this name",
+    ),
+    output_format: OutputFormat = typer.Option(
+        OutputFormat.JSON.value,
+        "--output-format",
+        help="Show the data in this format.",
+    ),
+    output_file: Path = typer.Option(
+        None,
+        "--file",
+        help="Write the data to a file with the specified name.",
+    ),
+    output_folder: Path = typer.Option(
+        Path.cwd(),
+        "--output-folder",
+        help="Output folder. Defaults to current working directory",
+        show_default=False,
+    ),
+    detailed_output: bool = typer.Option(
+        False,
+        "--detailed-output",
+        help="Output detailed output." " When False you will get basic energy usage and emissions results",
+    ),
+    date_format_option: DateFormat = typer.Option(
+        DateFormat.ISO_8601.value,
+        "--date-format-option",
+        help='Date format option. 0: "YYYY-MM-DD HH:MM:SS" (Accepted variant of ISO8601), 1: "YYYYMMDD HH:MM:SS" (ISO8601), 2: "DD.MM.YYYY HH:MM:SS". Default 0 (ISO 8601)',
+    ),
+    output_frequency: Frequency = typer.Option(
+        libecalc.common.time_utils.Frequency.NONE.name,
+        "--output-frequency",
+        "-f",
+        help="Frequency of output. Options are DAY, MONTH, YEAR. If not specified, it will give"
+        " time steps equal to the union of all input given with INFLUENCE_TIME_VECTOR set to True."
+        " Down-sampling the result may lead to loss of data, and rates such as MW may not add up to cumulative values",
+    ),
+):
+    """Show results. You need to run eCalc™ before this will be available."""
+    cache = Cache(user_specified_output_path=output_folder)
+    results = cache.load_results()
+    run_info = cache.load_run_info()
+
+    if run_info.version != libecalc.version.current_version():
+        logger.warning(
+            f"Your version of eCalc™ '{libecalc.version.current_version()}' is different to the one used to create the results '{run_info.version}'."
+        )
+
+    if output_frequency != Frequency.NONE:
+        results_resampled = results.resample(libecalc.common.time_utils.Frequency[output_frequency.name])
+    else:
+        results_resampled = results.model_copy()
+
+    component_name = component_name
+
+    if component_name is None:
+        # Default to full result if no specified component.
+        text = get_result_output(
+            results_resampled,
+            output_format=output_format,
+            simple_output=not detailed_output,
+            date_format_option=int(date_format_option.value),
+        )
+    else:
+        text = get_component_output(
+            results_resampled,
+            component_name,
+            output_format=output_format,
+            simple_output=not detailed_output,
+            date_format_option=int(date_format_option.value),
+        )
+
+    write_output(text, output_file)

ecalc_cli/errors.py

@@ -0,0 +1,4 @@
+class EcalcCLIError(Exception):
+    """Placeholder for user-facing exception handling. TODO: Add sanitation."""
+
+    pass

ecalc_cli/io/cache.py

@@ -0,0 +1,108 @@
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from libecalc import dto
+from libecalc.application.graph_result import EnergyCalculatorResult, GraphResult
+from libecalc.common.run_info import RunInfo
+from libecalc.dto.base import EcalcBaseModel
+from libecalc.presentation.json_result.mapper import get_asset_result
+from libecalc.presentation.json_result.result import EcalcModelResult
+
+from ecalc_cli.logger import logger
+
+
+class CacheData(EcalcBaseModel):
+    """Data model for content in cache."""
+
+    component_dto: dto.Asset
+    results: EnergyCalculatorResult
+
+
+@dataclass
+class Cache:
+    """Data class for CLI cache, storing model, results and run info."""
+
+    user_specified_output_path: Path
+    cache_path: Path = field(init=False)
+    results_path: Path = field(init=False)
+    run_info_path: Path = field(init=False)
+
+    def __post_init__(self):
+        self.cache_path = self.user_specified_output_path / ".ecalc"
+        self.cache_path.mkdir(mode=0o770, exist_ok=True)
+        self.results_path = self.cache_path / "results.json"
+        self.run_info_path = self.cache_path / "run_info.json"
+
+    def write_results(self, results: GraphResult, component_dto: dto.Asset):
+        """Write results to cache.
+
+        Args:
+            results: Model results
+            component_dto: Model used
+
+        Returns:
+
+        """
+        logger.info(f"Writing results to cache '{self.cache_path}'.")
+        self.results_path.touch(mode=0o660, exist_ok=True)
+        cache_data = CacheData(
+            results=results.get_results(),
+            component_dto=component_dto,
+        )
+        self.results_path.write_text(cache_data.model_dump_json())
+
+    def write_run_info(self, run_info: RunInfo):
+        """Write meta information about the run to the cache.
+
+        Args:
+            run_info: A data model containing meta data of a eCalc run
+
+        Returns:
+
+        """
+        logger.info(f"Writing run info to cache '{self.cache_path}'.")
+        self.run_info_path.touch(mode=0o660, exist_ok=True)
+        self.run_info_path.write_text(run_info.model_dump_json())
+
+    def load_run_info(self) -> RunInfo:
+        """Load metadata about run from cache.
+
+        Returns:
+            Cached metadata about a eCalc run
+
+        Raises:
+            ValueError: If the run info filepath is not set.
+
+        """
+        if not self.run_info_path.is_file():
+            msg = "Could not find run info in this directory. Run the model again to generate results."
+            logger.error(msg)
+            raise ValueError(msg)
+
+        return RunInfo.model_validate_json(self.run_info_path.read_text())
+
+    def load_results(self) -> EcalcModelResult:
+        """Load cached results from an ecalc run.
+
+        Returns:
+            Ecalc run results for a model
+
+        Raises:
+            ValueError: If the results path is not set
+
+        """
+        if not self.results_path.is_file():
+            msg = "Could not find results in this directory, make sure you run 'ecalc show' from the output directory of 'ecalc run' (or specify --outputfolder). Run the model again if no output directory exists."
+            raise ValueError(msg)
+        cached_text = self.results_path.read_text()
+        cache_data = CacheData.model_validate_json(cached_text)
+        graph = cache_data.component_dto.get_graph()
+
+        return get_asset_result(
+            GraphResult(
+                graph=graph,
+                emission_results=cache_data.results.emission_results,
+                consumer_results=cache_data.results.consumer_results,
+                variables_map=cache_data.results.variables_map,
+            )
+        )