lume-model 1.7.1__tar.gz

lume_model-1.7.1/.gitattributes

@@ -0,0 +1 @@
+lume_model/_version.py export-subst

lume_model-1.7.1/.github/workflows/build_docs.yml

@@ -0,0 +1,29 @@
+name: Build docs
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    if: ${{ github.repository == 'slaclab/lume-model' }}
+    runs-on: ubuntu-latest
+    name:  Build docs
+    steps:
+      - uses: actions/checkout@v4
+      - uses: conda-incubator/setup-miniconda@v3
+        with:
+          python-version: 3.9
+          mamba-version: "*"
+          channels: conda-forge
+          activate-environment: lume-model-dev
+      - name: Build package
+        shell: bash -l {0}
+        run: |
+          pip install -e ".[docs]"
+      - name: Build docs
+        shell: bash -l {0}
+        run: |
+          mkdocs build
+          mkdocs gh-deploy --force

lume_model-1.7.1/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish Python distributions to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-n-publish:
+    if: ${{ github.repository == 'slaclab/lume-model' }}
+    name: Build and publish Python distributions to PyPI
+    runs-on: ubuntu-latest
+    environment: deployment
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build
+        run: |
+          python -m pip install build --user
+      - name: Build a source tarball
+        run: |
+          python -m build
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

lume_model-1.7.1/.github/workflows/test_build.yml

@@ -0,0 +1,45 @@
+name: Test build lume-model
+
+on:
+  push:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.9", "3.11", "3.12"]
+
+    name: Python ${{ matrix.python-version }}, ${{ matrix.os }} build
+    steps:
+      - uses: actions/checkout@v4
+      - uses: conda-incubator/setup-miniconda@v3
+        with:
+          python-version: ${{ matrix.python-version }}
+          miniforge-version: latest
+          use-mamba: true
+          channels: conda-forge
+          activate-environment: lume-model-dev
+
+      - name: Install lume-model
+        shell: bash -l {0}
+        run: |
+          pip install -e ".[dev]"
+
+      - name: Run Tests
+        shell: bash -l {0}
+        run: |
+          pytest -ra --pyargs tests
+
+      - name: Install build
+        shell: bash -l {0}
+        run: |
+          python -m pip install build  --user
+
+      - name: Build a source tarball
+        shell: bash -l {0}
+        run: |
+          python -m build

lume_model-1.7.1/.github/workflows/test_build_docs.yml

@@ -0,0 +1,27 @@
+name: Build docs
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  build:
+    if: ${{ github.repository == 'slaclab/lume-model' }}
+    runs-on: ubuntu-latest
+    name:  Build docs
+    steps:
+      - uses: actions/checkout@v4
+      - uses: conda-incubator/setup-miniconda@v3
+        with:
+          python-version: 3.9
+          mamba-version: "*"
+          channels: conda-forge
+          activate-environment: lume-model-dev
+      - name: Build package
+        shell: bash -l {0}
+        run: |
+          pip install -e ".[docs]"
+      - name: Build docs
+        shell: bash -l {0}
+        run: |
+          mkdocs build

lume_model-1.7.1/.gitignore

@@ -0,0 +1,138 @@
+# Auto-generated version file
+lume_model/_version.py
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# PyCharm project settings
+.idea
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# macOS file system
+.DS_Store

lume_model-1.7.1/.pre-commit-config.yaml

@@ -0,0 +1,46 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks.git
+    rev: v4.6.0
+    hooks:
+      - id: no-commit-to-branch
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-ast
+      - id: check-case-conflict
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: check-xml
+      - id: check-yaml
+        exclude: "^(python/lume_model/_version.py)$"
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.5.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+#- repo: local
+#  hooks:
+#    - id: black
+#      name: black
+#      entry: black
+#      language: python
+#      language_version: python3
+#      types: [python]
+#      args: # arguments to configure black
+#        - --line-length=88
+#    - id: flake8
+#      name: flake8
+#      entry: flake8
+#      language: python
+#      language_version: python3
+#      types: [python]
+#      # only in lume_services
+#      files: ^lume_services
+#      args: # arguments to configure flake8
+#        # making isort line length compatible with black
+#        - "--max-line-length=88"

lume_model-1.7.1/LICENSE

@@ -0,0 +1,42 @@
+Copyright (c) 2017-2020, The Board of Trustees of the Leland Stanford
+Junior University, through SLAC National Accelerator Laboratory
+(subject to receipt of any required approvals from the U.S. Dept. of
+Energy). All rights reserved. Redistribution and use in source and
+binary forms, with or without modification, are permitted provided
+that the following conditions are met:
+
+(1) Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+
+(2) Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+(3) Neither the name of the Leland Stanford Junior University, SLAC
+National Accelerator Laboratory, U.S. Dept. of Energy nor the names of
+its contributors may be used to endorse or promote products derived
+from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER, THE UNITED STATES GOVERNMENT, OR CONTRIBUTORS BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
+GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+You are under no obligation whatsoever to provide any bug fixes,
+patches, or upgrades to the features, functionality or performance of
+the source code ("Enhancements") to anyone; however, if you choose to
+make your Enhancements available either publicly, or directly to SLAC
+National Accelerator Laboratory, without imposing a separate written
+license agreement for such Enhancements, then you hereby grant the
+following license: a non-exclusive, royalty-free perpetual license to
+install, use, modify, prepare derivative works, incorporate into other
+computer software, distribute, and sublicense such Enhancements or
+derivative works thereof, in binary and source code form.

lume_model-1.7.1/PKG-INFO

@@ -0,0 +1,320 @@
+Metadata-Version: 2.1
+Name: lume-model
+Version: 1.7.1
+Summary: Data structures used in the LUME modeling toolset.
+Author: SLAC National Accelerator Laboratory
+License: Copyright (c) 2017-2020, The Board of Trustees of the Leland Stanford
+        Junior University, through SLAC National Accelerator Laboratory
+        (subject to receipt of any required approvals from the U.S. Dept. of
+        Energy). All rights reserved. Redistribution and use in source and
+        binary forms, with or without modification, are permitted provided
+        that the following conditions are met:
+        
+        (1) Redistributions of source code must retain the above copyright
+        notice, this list of conditions and the following disclaimer.
+        
+        (2) Redistributions in binary form must reproduce the above copyright
+        notice, this list of conditions and the following disclaimer in the
+        documentation and/or other materials provided with the distribution.
+        
+        (3) Neither the name of the Leland Stanford Junior University, SLAC
+        National Accelerator Laboratory, U.S. Dept. of Energy nor the names of
+        its contributors may be used to endorse or promote products derived
+        from this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+        "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+        LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+        A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+        OWNER, THE UNITED STATES GOVERNMENT, OR CONTRIBUTORS BE LIABLE FOR ANY
+        DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
+        GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+        INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+        IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+        OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+        ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+        You are under no obligation whatsoever to provide any bug fixes,
+        patches, or upgrades to the features, functionality or performance of
+        the source code ("Enhancements") to anyone; however, if you choose to
+        make your Enhancements available either publicly, or directly to SLAC
+        National Accelerator Laboratory, without imposing a separate written
+        license agreement for such Enhancements, then you hereby grant the
+        following license: a non-exclusive, royalty-free perpetual license to
+        install, use, modify, prepare derivative works, incorporate into other
+        computer software, distribute, and sublicense such Enhancements or
+        derivative works thereof, in binary and source code form.
+        
+Project-URL: Homepage, https://github.com/slaclab/lume-model
+Project-URL: Documentation, https://slaclab.github.io/lume-model/
+Project-URL: Bug Tracker, https://github.com/slaclab/lume-model/issues
+Keywords: machine learning,accelerator physics
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic
+Requires-Dist: numpy
+Requires-Dist: pyyaml
+Provides-Extra: dev
+Requires-Dist: botorch<0.11; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocstrings; extra == "docs"
+Requires-Dist: mkdocstrings-python; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+
+# LUME-model
+
+LUME-model holds data structures used in the LUME modeling toolset. Variables and models built using LUME-model will be compatible with other tools. LUME-model uses [pydantic](https://pydantic-docs.helpmanual.io/) models to enforce typed attributes upon instantiation.
+
+## Requirements
+
+* Python >= 3.9
+* pydantic
+* numpy
+
+## Install
+
+LUME-model can be installed with conda using the command:
+
+``` $ conda install lume-model -c conda-forge ```
+
+## Developer
+
+A development environment may be created using the packaged `dev-environment.yml` file.
+
+```
+conda env create -f dev-environment.yml
+```
+
+## Variables
+
+The lume-model variables are intended to enforce requirements for input and output variables by variable type. For now, only scalar variables (floats) are supported.
+
+Minimal example of scalar input and output variables:
+
+```python
+from lume_model.variables import ScalarInputVariable, ScalarOutputVariable
+
+input_variable = ScalarInputVariable(
+    name="example_input",
+    default=0.1,
+    value_range=[0.0, 1.0],
+)
+output_variable = ScalarOutputVariable(name="example_output")
+```
+
+All input variables may be made into constants by passing the `is_constant=True` keyword argument. Value assingments on these constant variables will raise an error message.
+
+## Models
+
+The lume-model base class `lume_model.base.LUMEBaseModel` is intended to guide user development while allowing for flexibility and customizability. It is used to enforce LUME tool compatible classes for the execution of trained models.
+
+Requirements for model classes:
+
+* input_variables: A list defining the input variables for the model. Variable names must be unique. Required for use with lume-epics tools.
+* output_variables: A list defining the output variables for the model. Variable names must be unique. Required for use with lume-epics tools.
+* evaluate: The evaluate method is called by the serving model. Subclasses must implement this method, accepting and returning a dictionary.
+
+Example model implementation and instantiation:
+
+```python
+from lume_model.base import LUMEBaseModel
+from lume_model.variables import ScalarInputVariable, ScalarOutputVariable
+
+
+class ExampleModel(LUMEBaseModel):
+    def evaluate(self, input_dict):
+        output_dict = {
+            "output1": input_dict[self.input_variables[0].name] ** 2,
+            "output2": input_dict[self.input_variables[1].name] ** 2,
+        }
+        return output_dict
+
+
+input_variables = [
+    ScalarInputVariable(name="input1", default=0.1, value_range=[0.0, 1.0]),
+    ScalarInputVariable(name="input2", default=0.2, value_range=[0.0, 1.0]),
+]
+output_variables = [
+    ScalarOutputVariable(name="output1"),
+    ScalarOutputVariable(name="output2"),
+]
+
+m = ExampleModel(input_variables=input_variables, output_variables=output_variables)
+```
+
+## Configuration files
+
+Models and variables may be constructed using a YAML configuration file. The configuration file consists of three sections:
+
+* model (optional, can alternatively pass a custom model class into the `model_from_yaml` method)
+* input_variables
+* output_variables
+
+The model section is used for the initialization of model classes. The `model_class` entry is used to specify the model class to initialize. The `model_from_yaml` method will attempt to import the specified class. Additional model-specific requirements may be provided. These requirements will be checked before model construction. Model keyword arguments may be passed via the config file or with the function kwarg `model_kwargs`. All models are assumed to accept `input_variables` and `output_variables` as keyword arguments.
+
+For example, `m.dump("example_model.yml")` writes the following to file
+
+```yaml
+model_class: ExampleModel
+input_variables:
+  input1:
+    variable_type: scalar
+    default: 0.1
+    is_constant: false
+    value_range: [0.0, 1.0]
+  input2:
+    variable_type: scalar
+    default: 0.2
+    is_constant: false
+    value_range: [0.0, 1.0]
+output_variables:
+  output1: {variable_type: scalar}
+  output2: {variable_type: scalar}
+```
+
+and can be loaded by simply passing the file to the model constructor:
+
+```python
+from lume_model.base import LUMEBaseModel
+
+
+class ExampleModel(LUMEBaseModel):
+    def evaluate(self, input_dict):
+        output_dict = {
+            "output1": input_dict[self.input_variables[0].name] ** 2,
+            "output2": input_dict[self.input_variables[1].name] ** 2,
+        }
+        return output_dict
+
+
+m = ExampleModel("example_model.yml")
+```
+
+## PyTorch Toolkit
+
+In the same way as the KerasModel, a PyTorchModel can also be loaded using the `lume_model.utils.model_from_yaml` method, specifying `PyTorchModel` in the `model_class` of the configuration file.
+
+```yaml
+model:
+  kwargs:
+    model_file: /path/to/california_regression.pt
+  model_class: lume_model.torch.PyTorchModel
+  model_info: path/to/model_info.json
+  output_format:
+    type: tensor
+  requirements:
+    torch: 1.12
+```
+
+In addition to the model_class, we also specify the path to the pytorch model (saved using `torch.save()`) and additional information about the model through the `model_info.json` file such as the order of the feature names and outputs of the model:
+
+```json
+{
+    "train_input_mins": [
+        0.4999000132083893,
+        ...
+        -124.3499984741211
+    ],
+    "train_input_maxs": [
+        15.000100135803223,
+        ...
+        -114.30999755859375
+    ],
+    "model_in_list": [
+        "MedInc",
+        ...
+        "Longitude"
+    ],
+    "model_out_list": [
+        "MedHouseVal"
+    ],
+    "loc_in": {
+        "MedInc": 0,
+        ...
+        "Longitude": 7
+    },
+    "loc_out": {
+        "MedHouseVal": 0
+    }
+}
+```
+
+The `output_format` specification indicates which form the outputs of the model's `evaluate()` function should take, which may vary depending on the application. PyTorchModels working with the [LUME-EPICS](https://github.com/slaclab/lume-epics) service will require an `OutputVariable` type, while [Xopt](https://github.com/ChristopherMayes/Xopt) requires either a dictionary of float values or tensors as output.
+
+It is important to note that currently the **transformers are not loaded** into the model when using the `model_from_yaml` method. These need to be created separately and added either:
+
+* to the model's `kwargs` before instantiating
+
+```python
+import torch
+import json
+from lume_model.torch import PyTorchModel
+
+# load the model class and kwargs
+with open(f"california_variables.yml","r") as f:
+  yaml_model, yaml_kwargs = model_from_yaml(f, load_model=False)
+
+# construct the transformers
+with open("normalization.json", "r") as f:
+  normalizations = json.load(f)
+
+input_transformer = AffineInputTransform(
+    len(normalizations["x_mean"]),
+    coefficient=torch.tensor(normalizations["x_scale"]),
+    offset=torch.tensor(normalizations["x_mean"]),
+)
+output_transformer = AffineInputTransform(
+    len(normalizations["y_mean"]),
+    coefficient=torch.tensor(normalizations["y_scale"]),
+    offset=torch.tensor(normalizations["y_mean"]),
+)
+
+model_kwargs["input_transformers"] = [input_transformer]
+model_kwargs["output_transformers"] = [output_transformer]
+
+model = PyTorchModel(**model_kwargs)
+```
+
+* using the setters for the transformer attributes in the model.
+
+```python
+# load the model
+with open("california_variables.yml", "r") as f:
+  model = model_from_yaml(f, load_model=True)
+
+# construct the transformers
+with open("normalization.json", "r") as f:
+  normalizations = json.load(f)
+
+input_transformer = AffineInputTransform(
+    len(normalizations["x_mean"]),
+    coefficient=torch.tensor(normalizations["x_scale"]),
+    offset=torch.tensor(normalizations["x_mean"]),
+)
+output_transformer = AffineInputTransform(
+    len(normalizations["y_mean"]),
+    coefficient=torch.tensor(normalizations["y_scale"]),
+    offset=torch.tensor(normalizations["y_mean"]),
+)
+
+# use the model's setter to add the transformers. Here we use a tuple
+# to tell the setter where in the list the transformer should be inserted.
+# In this case because we only have one, we add them at the beginning
+# of the lists.
+model.input_transformers = (input_transformer, 0)
+model.output_transformers = (output_transformer, 0)
+```