v0.6.5

Changes

Estimators

• Added a Physics-Informed CNN estimator for 1D Turbulence
  • example in 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()
  • load_model() - corresponding to 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

v0.6.2

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

v0.6.1

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

v0.6.0

Changes

Wiki

• Brand New! Created with mkdocs-material: 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
  • 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

v0.5.0

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
  • the method was published in P.I.Karpov et al, 2022
  • wiki page: 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

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 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

v0.4.8

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

v0.4.7

Changes

Data Loading

• Fixed: using multiple checkpoints when batch_num is not specified
  • before data would load from all checkpoints, but only the 1st one would be used for training by default

Training log plot

• Fixed: if training log fails, the plot was producing and error, with the trained model not being saved
  • happened sometimes during the long training sessions
  • log plotting no longer affects model output

v0.4.6

Changes

Filters

• Fixed: compatibility with the latest opencv-python ( >=4.5.4)
  • 2D box filter is now working correctly

Subgrid Model

• Updated: Dynamic Smagorinsky model
  • improved initialization
  • added 2D support

Evaluation

• Removed: a redundant parameter requirement in Evaluate()
  • 'flat' condition is now passed along with other input data parameters in data_loader

v0.4.5

Changes

Distributed Data Parallel (DDP)

• Fixed: DistributedDataParallel (DDP)
  • engine is no longer overwritten
  • will be determined automatically by Catalist if ddp=True
  • can always be customized by hand (Parallel GPU Training)
• Updated: device in Run Info better reflects if attempting to run in parallel

MLflow

• Returned auto-termination of MLflow tracking after Evaluation.run()
  • cleans up MLflow logging (was getting messy before, when loading the model to evaluate without training)

Plotting

• Updated: default plot formatting

  • colormaps are colorblind friendly now (tableau-colorblind10 and viridis)
  • log ticks are inward + size adjustment for a cleaner look
  • thin dotted default grid
  • you can always call sapsan.utils.plot.plot_params(), which returns the full set of default parameters

• Updated: spectrum_plot formatting for consistency with other plotting routines

  • Renamed: plot_spectrum() -> spectrum_plot()
  • Now returns Axes object, as do others

Command Line Interface (CLI)

• Renamed: --ddp -> --gtb or --get_torch_backend option for sapsan
  • to copy torch_backend.py when creating the project: sapsan create --gtb -n {name}
• New Command: sapsan get_torch_backend
  • copies torch_backend.py into your working directory
  • this allows you to not have to 'create' a project to copy the backend
  • you can proceed to edit the Catalyst runner (custom loss, optimizer, DDP config, etc.)

Custom Estimator

• Added: a guide on how to go deeper and edit Catalyst runner
• Added: a convenient command to copy torch_backend.py in your working directory (see above)

Gradient Model

• Fixed: derivative multiplication
• Fixed: model calculation consistency

Other

• Renamed: tensor() -> ReynoldsStress() to avoid confusion
• Documentation updated accordingly

v0.4.4

Changes

MLflow

• New parameters for Train() and Evaluate()
  • run_id parameter after run() has been called
    • allows to resume and record to a specific run at a later time
  • run_name to change the recorded run names
    • by default, they are train and evaluate as recorded in MLflow
• One can add new metrics/parameters/artifacts after Train or Evaluate have completed
  • either Sapsan's backend interface or a traditional MLflow interface can be used
  • Wiki update: MLflow Tracking
• Changes to MLflowBackend()
  • while loop for close_active_run() to make sure all runs have been closed
  • new function resume() which requires to provide the run_id to resume and record to the run
    • nested = True by default
  • Wiki update: API Reference: Backend (Tracking)

Plotting

• New parameter for cdf_plot
  • ks - controls to print Kolmogorov-Smirnov Statistic on the plot itself
    • also outputs it as ax, ks = cdf_plot(...)
• New parameters for Evaluate
  • pdf_xlim, pdf_ylim - x and y limits to control the pdf plot
  • cdf_xlim, cdf_ylim - same for the cdf plot
• Fixed: model_graph
  • no longer sets number of channels to 1
  • the easiest way to construct the graph is to pass the training loader shape
  • Wiki update: Model Graph

Graphical User Interface (GUI)

• GUI examples are now included in PyPi
  • sapsan/examples/GUI
• The file structure has been simplified
  • unnecessary files removed
• The scripts have been cleaned up, with more comments, and a clearer function organization to aid editing
• Brought up to date with the most recent Sapsan version
• Core package has been locked to streamlit == 0.84.2
  • there is a known bug causing pd.DataFrames to not display properly
  • will update once Streamlit team fixes those issues
• Wiki update: GUI Examples

Command Line Interface (CLI)

• Changes to sapsan get_examples
  • GUI examples will be copied as well, found in ./sapsan-examples/GUI

Other

• Fixed the exact device ID issue: affected the multi-GPU systems
  • tensors no longer move only to the default (cuda:0), but to a correct device id
• Updated the requirements template