Packaging core routines

[dreamer2368]

This PR provides a skeleton for python packaging the repository. Currently it is implemented based on 1D burger's equation example. If there are additional features in other examples, they will be added in future PRs.

I intend this PR to be an initial groundwork, not necessarily completing everything in this one PR, so that we keep the amount of PRs smaller, easier for review.

In pip installation, current version is set as 2.0.0dev. The current official release will be marked as 1.0.0 in the repository.

pyproject.toml

pyproject.toml file specifies the configuration for installation. All prerequisites and the core modules can be installed via

pip install .

at the repository.

• pip package for this repository is named as lasdi. Although this repository only has GPLasDI, I'm hoping to set this as a placeholder for all variations of LasDI. I'm open for other suggestions though.
• the python prerequisites are updated for the core modules. See Prerequisites updated below.
• The core modules are provided as part of the python package that will be installed via pip. For details, see Core routines for GPLasDI below.
• the installed package lasdi will also provide an executable lasdi, which will provide the workflow interface with FOM simulations outside this package. For details, see Executable for the main workflow below.

Running an example

Currently input file/postprocess of burgers 1d equation is provided at examples directory. Once pip installation is finished, run the example on the terminal to generate data/train the model:

cd example
lasdi burgers1d.yml

Postprocess and visualization is demonstrated on jupyter notebook examples/burgers1d.ipynb.

NOTE: Currently most post-process/visualization routines are copy-pasted from the legacy code. There will be a significant refactoring in future.

Prerequisites updated

Updated prerequisites are specified in pyproject.toml as below:

dependencies = [
  "torch>=2.3.0",
  "numpy>=1.26.4",
  "scikit-learn>=1.4.2",
  "scipy>=1.13.1",
  "pyyaml>=6.0",
  "matplotlib>=3.8.4",
  "argparse>=1.4.0"
]

Core routines of GPLasDI

The legacy code has been provided specific to each physics example, and the users had to revise the code according to their applications. We intend to store some core routines that are common to all applications:

Each file in src directory can be imported as a python module, once installed via pip. For example, src/lasdi/gplasdi.py can be imported as

from lasdi import gplasdi

Following are the main modules for the training:

• lasdi.sindy: routines related to SInDy training/prediction.
• lasdi.latent_space: routines related to latent space autoencoders. Autoencoder class is included here.
• lasdi.interp: routines for interpolation of sindy coefficients in parameter space.
• lasdi.gplasdi: routines for GPLasDI training. BayesianGLasDI class is included here.
• lasdi.physics: routines for built-in physics simulations. For now, only lasdi.physics.burgers1d module is provided. The 4 examples in the legacy code will be incorporated into this module in future.
• lasdi.workflow: routines for training workflow and interface with offline FOM simulation. for details, see Executable for the main workflow below.
• lasdi.postprocess: routines for post-processing/visualization. There will be significant refactorings on this module in future.

Executable for the main workflow

For production runs, the training workflow needs to be combined with offline FOM simulations for sampling. This means that we cannot run the entire workflow within a single python for-loop: we run each step of the training iterations, and decide at some point to run a FOM simulation outside the python framework, and come back after collecting FOM snapshot.

The executable lasdi is developed with the intention for interfacing the python training routine and the offline FOM simulation. All related functions are stored in src/lasdi/workflow.py:

• main function is the routine that is run by the executable lasdi. It reads a config yaml file that specifies the required inputs for the entire workflow. The inputs include those options in generate_data.py and train_model1.py of the legacy code. It runs step function based on the input file.
• step function runs various stages of the training workflow, depending on the previous output of NextStep and Result. These enumerations are stored in src/lasdi/enums.py.

Currently, this only supports the 1D burger's equation, with the entire workflow fully run on python. The example config file for this is stored in examples/burgers1d.yml. The more generalized workflow will be provided in future PRs.

Legacy codes

The existing codes for 4 examples (1d/2d burgers equation, rising bubble and vlasov equation) remain the same. They are still under the old prerequisites for version 1.0.0. They are also not included in the pip installation procedure as mentioned above. Users can still use them with old pre-requisites, as they have done before. In future, they will be all incorporated into the core modules, with the updated pre-requisites.

[andersonw1]

This looks really good! I am going to start going through it

[chldkdtn]

I like this direction!

[CBonneville45]

Looking good!

[andersonw1]

I was able to produce accurate results for 1DBurger's using the updated packages/files added here. Nice contribution!