Lattice QCD integration

use-cases/lattice-qcd/CITATION.cff

@@ -0,0 +1,26 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
+cff-version: 1.2.0
+title: normflow_
+message: >-
+  If you use this software, please cite it using the
+  metadata from this file.
+type: software
+authors:
+  - given-names: Javad
+    family-names: Komijani
+    email: [email protected]
+    affiliation: ETH Zurich
+    orcid: 'https://orcid.org/0000-0002-6943-8735'
+  - given-names: Gaurav
+    family-names: Ray
+    email: [email protected]
+    affiliation: CSIC
+    orcid: 'https://orcid.org/0000-0003-1956-7659'
+repository-code: 'https://github.com/jkomijani/normflow_'
+abstract: >-
+  Normalizing flow for generating lattice field
+  configurations. This release handles the scalar theories.
+version: v1.1.0-beta
+date-released: '2024-02-02'

use-cases/lattice-qcd/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

use-cases/lattice-qcd/CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# How can I contribute?
+
+## Reporting bugs
+
+## Suggesting improvement
+
+## Pull requests
+
+## Style guide
+
+### git commit message
+
+### python code style 

use-cases/lattice-qcd/INSTALL

@@ -0,0 +1,5 @@
+To install:
+    python3 -m pip install . --user
+
+To uninstall:
+    python3 -m pip uninstall normflow

use-cases/lattice-qcd/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-2022 Javad Komijani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

use-cases/lattice-qcd/README.md

@@ -0,0 +1,181 @@
+normflow
+[![SQAaaS badge shields.io](https://img.shields.io/badge/sqaaas%20software-silver-lightgrey)](https://api.eu.badgr.io/public/assertions/-g9rQYZJTyi4S-VUrbvqlQ "SQAaaS silver badge achieved")
+[![License: MIT](https://cdn.prod.website-files.com/5e0f1144930a8bc8aace526c/65dd9eb5aaca434fac4f1c34_License-MIT-blue.svg)](/LICENSE)
+--------
+This package provides utilities for implementing the
+**method of normalizing flows** as a generative model for lattice field theory.
+
+The method of normalizing flows is a powerful generative modeling approach that
+learns complex probability distributions by transforming samples from a simple
+distribution through a series of invertible transformations. It has found
+applications in various domains, including generative image modeling.
+
+The package currently supports scalar theories in any dimension, and we are
+actively extending it to accommodate gauge theories, broadening its
+applicability.
+
+In a nutshell, three essential components are required for the method of
+normalizing flows:
+
+*   A **prior distribution** to draw initial samples.
+*   A **neural network** to perform a series of invertible transformations on
+    the samples.
+*   An **action** that specifies the target distribution, defining the goal of
+    the generative model.
+
+The central high-level class of the package is called `Model`, which can be
+instantiated by providing instances of the three objects mentioned above:
+the prior, the neural network, and the action.
+
+Following the terminology used by *scikit-learn*, each instance of `Model`
+comes with a `fit` method, responsible for training the model. For those who
+prefer an alternative to the scikit-learn terminology, an alias called `train`
+is also available and functions identically. The training process involves
+optimizing the parameters of the neural network to accurately map the prior
+distribution to the target distribution.
+
+
+Below is a simple example of a scalar theory in zero dimension, i.e.,
+a scenario with one point and one degree of freedom:
+
+
+```python
+from normflow import Model
+from normflow.action import ScalarPhi4Action
+from normflow.prior import NormalPrior
+from normflow.nn import DistConvertor_
+
+def make_model():
+    # Define the prior distribution
+    prior = NormalPrior(shape=(1,))
+
+    # Define the action for a scalar \phi^4 theory
+    action = ScalarPhi4Action(kappa=0, m_sq=-2.0, lambd=0.2)
+
+    # Initialize the neural network for transformations
+    net_ = DistConvertor_(knots_len=10, symmetric=True)
+
+    # Create the Model with the defined components
+    model = Model(net_=net_, prior=prior, action=action)
+
+    return model
+
+# Instantiate and train the model
+model = make_model()
+model.fit(n_epochs=1000, batch_size=1024, checkpoint_dict=dict(print_stride=100))
+```
+
+In this example, we have:
+
+-   **Prior Distribution**: A normal distribution is used with a shape of
+    `(1,)`; one could also set `shape=1`.
+
+-   **Action**: A quartic scalar theory is defined with parameters
+    `kappa=0`, `m_sq=-2.0`, and `lambda=0.2`.
+
+-   **Neural Network**: The `DistConvertor_` class is used to create the
+    transformation network, with `knots_len=10` and symmetry enabled.
+    Any instance of this class converts the probability distribution of inputs
+    using a rational quadratic spline. In this example, the spline has 10 knots,
+    and the distribution is assumed to be symmetric with respect to the origin.
+
+-   **Training**: The model is trained for `1000` epochs with a batch size of
+    `1024`. Progress is printed every `100` epochs.
+
+This example demonstrates the flexibility of using the package to implement
+scalar field theories in a simplified zero-dimensional setting. It can be
+generalized to any dimension by changing the shape provided to the prior
+distribution.
+
+The above code block results in an output similar to:
+
+    >>> Checking the current status of the model <<<
+    Epoch: 0 | loss: -1.8096 | ess: 0.4552 | log(p): 0.4(11)
+    >>> Training started for 1000 epochs <<<
+    Epoch: 100 | loss: -2.0154 | ess: 0.6008 | log(p): 0.52(57)
+    Epoch: 200 | loss: -2.1092 | ess: 0.7381 | log(p): 0.60(56)
+    Epoch: 300 | loss: -2.1612 | ess: 0.8195 | log(p): 0.57(87)
+    Epoch: 400 | loss: -2.2091 | ess: 0.8783 | log(p): 0.63(83)
+    Epoch: 500 | loss: -2.2459 | ess: 0.9262 | log(p): 0.71(58)
+    Epoch: 600 | loss: -2.2670 | ess: 0.9459 | log(p): 0.73(56)
+    Epoch: 700 | loss: -2.2684 | ess: 0.9585 | log(p): 0.74(53)
+    Epoch: 800 | loss: -2.2667 | ess: 0.9684 | log(p): 0.74(51)
+    Epoch: 900 | loss: -2.2724 | ess: 0.9789 | log(p): 0.76(54)
+    Epoch: 1000 | loss: -2.2673 | ess: 0.9791 | log(p): 0.75(62)
+    >>> Training finished (cpu); TIME = 4.36 sec <<<
+
+
+This output indicates the loss values at specified epochs during the training
+process, providing insight into the model's performance over time.
+
+
+After training the model, one can draw samples using an attribute called
+`posterior`.
+To draw `n` samples from the trained distribution, use the following command:
+
+```python
+x = model.posterior.sample(n)
+```
+
+Note that the trained distribution is almost never identical to the target
+distribution, which is specified by the action. To generate samples that are
+correctly drawn from the target distribution, similar to Markov Chain Monte
+Carlo (MCMC) simulations, one can employ a Metropolis accept/reject step and
+discard some of the initial samples. To this end, you can use the following
+command:
+
+```python
+x = model.mcmc.sample(n)
+```
+
+This command draws `n` samples from the trained distribution and applies a
+Metropolis accept/reject step to ensure that the samples are correctly drawn.
+
+<p align="center">
+    <img src="docs/images/Normflow.png" alt="Block diagram for the method of normalizing flows" width="80%" />
+</p>
+<p align="center">
+    Block diagram for the method of normalizing flows
+</p>
+
+
+The *TRAIN* and *GENERATE* blocks in the above figure depict the procedures for
+training the model and generating samples/configurations. For more information
+see [arXiv:2301.01504](https://arxiv.org/abs/2301.01504).
+
+Moreover, the model has an attribute called `device_handler`, which can be used
+to specify the number of GPUs used for training (the default value is one if
+any GPU is available). To this end, you can use the following approach:
+
+```python
+def fit_func(model):
+    model.fit(n_epochs=1000, batch_size=1024)
+
+model.device_handler.spawnprocesses(fit_func, nranks)
+```
+
+In this code, `nranks` specifies the number of GPUs to be used for training.
+You can efficiently scale your model training across multiple GPUs, enhancing
+performance and reducing training time. This flexibility allows you to tackle
+larger datasets and more complex models with ease.
+
+In summary, this package provides a robust and flexible framework for
+implementing the method of normalizing flows as a generative model for lattice
+field theory. With its intuitive design and support for scalar theories, you
+can easily adapt it to various dimensions and leverage GPU acceleration for
+efficient training. We encourage you to explore the features and capabilities
+of the package, and we welcome contributions and feedback to help us improve
+and expand its functionality.
+
+## itwinai integration
+
+Integration of itwinai functionalities in normflow is based on changing the 
+implementation to `torchrun` enabling multi-node parallelism. This version 
+provides `train.py` file to execute the workflow. For working on HPC systems, 
+additionally a `startscript.sh` file is provided. This can be launched by:
+```sbatch startscript.sh```
+The version includes integration of loggers and profiling tools provided by
+itwinai. 
+
+| Created by Javad Komijani in 2021 \
+| Copyright (C) 2021-24, Javad Komijani