Sapsan

Changes

Estimators
* Added a [Physics-Informed CNN estimator for **1D** Turbulence](https://sapsan-wiki.github.io/details/estimators/#physics-informed-cnn-for-1d-turbulence-modeling-pimlturb1d)
* example in [pimlturb1d_example.ipynb](https://github.com/pikarpov-LANL/Sapsan/blob/master/sapsan/examples/pimlturb1d_example.ipynb)
* added a unit test on commit as well
* Gaussian filter layer now supports 1D

Examples
* New [plotting_examples.py]() that include tutorials on:
* line_plot
* slice_plot
* pdf_plot
* cdf_plot
* log_plot
* model_graph
* Adjusted example formatting to unify them in style
* Reduced the size of the example data by 50%

Plotting
* _Fixed:_ `model_graph()` - model visualizations are fully operational again
* it also now supports 1D graphs, as well as 2D and 3D

MLflow
* Added new methods
* `log_model()` - corresponding to [mlflow.pytorch.log_model()](https://mlflow.org/docs/latest/python_api/mlflow.pytorch.html#mlflow.pytorch.log_model)
* `load_model()` - corresponding to [mlflow.pytorch.load_model()](https://mlflow.org/docs/latest/python_api/mlflow.pytorch.html#mlflow.pytorch.load_model)

CLI
* _Fixed:_ `sapsan get_examples` not copying all examples

Training Backend
* Slowly transitioning away from Catalyst - it is no longer required for the model save/load routines
* Added TorchScript option
* _Fixed:_ `.next()` for `iter()` in evaluation module
* also `get_loader_shape` call of the loader's next iteration

Changes

Estimators
* _Fixed:_ PIMLturb compatibility with TorchScript for remote deployment
* other estimators should be already compatible

MLflow
* _Fixed:_ hanging indefinitely trying to auto-start the `mlflow ui`
* added a 30s timeout in case the given `port` is taken, but not with MLflow
* clear error message asking to change the `port`
* Default `port` is now `5000`, as per MLflow's standard defaults
* the previous one had a compatibility issue with WSL
* Latest MLflow version is now supported

Changes
Physics
* `PowerSpectrum` now supports velocity input in 1D, 2D, and 3D
* Cleaned-up `filters` code for legibility
* Kolmogorov doesn't include '0th' bin: no more warning

GUI
* *Fixed:* `Examples.py` widget parameter adjustment

Tests
* *Fixed:* test error if `resource_path` exists

Compatibility
* `mlflow>=1.20.1` -> **`mlflow>=1.20.1,<=1.25`**
* mlflow>=1.26 breaks ui client auto-startup

Other
* Examples' output has been updated

Changes

Wiki
* **Brand New!** Created with mkdocs-material: [sapsan-wiki.github.io](https://sapsan-wiki.github.io/)
* Powerful search function
* Redesigned API
* Improved navigation
* Versioning
* Dark mode: automatically adjusts based on system preferences
* Wiki on Github has been depreciated

Estimators
* Significant improvements to the `PIMLturb` estimator

- cleaned up redundancies improving the performance
and readability
- generalized the approach to calculate CDF and KS loss
- now works with the 1D CCSN calculations
- should be consistent no matter the scale of the data
- added `ks_frac`, `ks_scale`, `l1_scale`, `l1_beta`, `sigma` to be adjusted upon calling the estimator
- learn more at [PIMLTurb API](https://sapsan-wiki.github.io/api/#pimlturb)
- scientific notation for `PIMLturb` loss stdout
- Fixed `SmoothL1_KSLoss` train/valid output
- `PIMLturb` now logs the model, optimizer, and scheduler parameters through MLflow

GUI
* Updated GUI examples, adding compatibility with `streamlit=1.12.0`
- significant improvements to UI through st.expander

* Converted GUI to use `st.session_state` for all widgets
- that fixed config reloading
- included minor quality of life features
- significantly reduced the complexity of the code

* *Fixed:* editing the model code with jupyter notebooks
* Added:
* progress bar
* slice plots
* Dark Mode

CLI
* Lighter __init__, improved CLI speed x3
* Affected syntax:
* Past: `from sapsan import Train, Evaluate`
* New: `from sapsan.lib import Train, Evaluate`

* *Fixed:* paths with CLI commands

Examples
* Examples now include output
* Updated sample data for picae
* randomly sampled from a normal distribution
* Returned `FakeBackend()`
* makes it easier to disable logging everywhere in one line
* Cleaned up Examples to be up-to-date on comments


Plotting
* Beautified colormap bar
* always equals to the size of the plot itself
* slimmed down
* Added: `dpi` parameter to plot functions
* Default: `dpi=60` for all to avoid 'ballooning' in small margin jupyter notebooks
* Added: `cdf_plot()`, an exception if value ranges don't overlap, hence KS stat cannot be calculated

MLflow
* Train will try to log forward() of your model
- no longer Catalyst exclusive
- won't cause an error with scikit-learn

Compatibility

* Added: `python=3.9` and `3.10` support
* `streamlit==0.84.0` -> **`streamlit>=1.12.0`**
* major improvements
* not backward compatible

Other
* README: added shields.io badges to track sapsan and compatible python versions
* Fixed `setuptool` installation: `python setup.py install`
* Github Workflow updates and improvements. Added tests for PyPI, CLI, python 3.9, 3.10

Changes

Estimators
* Added a Physics-Informed CNN estimator used to predict diagonal Reynolds stress tensor terms for further turbulence pressure calculation
* [pimlturb_diagonal_estimator.py](https://github.com/pikarpov-LANL/Sapsan/blob/master/sapsan/lib/estimator/pimlturb/pimlturb_diagonal_estimator.py)
* the method was published in [P.I.Karpov et al, 2022](https://arxiv.org/abs/2205.08663)
* wiki page: [Physics-Informed CNN for Turbulence Modeling](https://github.com/pikarpov-LANL/Sapsan/wiki/Estimators#physics-informed-cnn-for-turbulence-modeling)

Examples
* Added PIMLTurb data at 17³ resolution & adjusted data path for examples
* Added PIMLTurb diagonal example with new torch_modules
* [pimlturb_diagonal_example.ipynb](https://github.com/pikarpov-LANL/Sapsan/blob/master/sapsan/examples/pimlturb_diagonal_example.ipynb)

Evaluation
* Added full support for 2D and 1D evaluations
* Plots: slices for 3D and 2D, profiles for 1D

Data Loading
* *Fixed:* `features_label` & `target_label` loading
* useful when different features are contained in the same .hdf5 file
* if `target` is not provided, but the `target_label` is given, the `target` will still be loaded
* *Fixed:* 1d data axis assignment
* `input_size` now takes lists

Plotting
* renamed `names` -> `labels` for plots
* now consistent with matplotlib
* Added `linestyle` argument to `line_plot()`
* Added new parameters for `log_plot()`
* aids flexibility for custom logs
* Review new parameters in the [API Plotting](https://github.com/pikarpov-LANL/Sapsan/wiki/API-Reference#plotting) under `log_plot()`


Package Compatibility

* Changed requirements:
* protobuf==3.20.*
* torch misbehaves with the latest protobuf
* numpy>=1.19.0 -> **numpy>=1.21.0**
* scipy>=1.5.2 -> **scipy>=1.7.3**
* scikit-learn>=0.23.2 -> **scikit-learn>=1.0.2**
* scikit0image>=0.17.2 -> **scikit-image>=0.19.3**
* Fixed issues with the KRR example

Changes

Import Sapsan
* Considerably faster package loading
- Estimators are no longer loaded on `__init__`: frees up memory

Training
* Improved `torch_backend.set_device()` to assign exact device index
- relays device passed to config
* _Fixed_: cleanup won't cause an error if artifacts are misplaced

Training log plot
* Added `valid_loss` to be plotted in `runtime_log plot`

Data Loading
* Added new parameter to HDF5Dataset: `batch_num`
- sets the number of batches to be loaded at a time
- helps with memory
- loss is averaged over all checkpoints
- Ex: you have 10 batches to train on, you can load 1 at a time for training
- updated the API in the Wiki on github

MLflow
* _Fixed_: MLflow ui auto-start freeze
- added a check if a port is free: if True - mlflow ui will start, if False - it will try to set an mlflow experiment

Package Compatibility
* Locked Catalyst to version `>=21.5, <=21.12`
- hot fix
- Catalyst 22.0+ changed its conventions,
which broke device/engine setup and logging