{"id":50800972,"url":"https://github.com/Koopman-Laboratory/KoopmanLab","last_synced_at":"2026-06-30T02:00:30.831Z","repository":{"id":65498856,"uuid":"580731435","full_name":"Koopman-Laboratory/KoopmanLab","owner":"Koopman-Laboratory","description":"A library for Koopman Neural Operator with Pytorch.","archived":false,"fork":false,"pushed_at":"2024-10-05T03:08:27.000Z","size":593,"stargazers_count":314,"open_issues_count":9,"forks_count":25,"subscribers_count":7,"default_branch":"main","last_synced_at":"2026-01-28T22:56:43.658Z","etag":null,"topics":["deep-learning","koopman","neural-network","neural-operator","pytorch","scientific-machine-learning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Koopman-Laboratory.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-12-21T09:58:28.000Z","updated_at":"2026-01-20T08:58:14.000Z","dependencies_parsed_at":"2023-11-30T11:27:40.568Z","dependency_job_id":"2178c0bc-1010-43dd-b976-cc65715ae376","html_url":"https://github.com/Koopman-Laboratory/KoopmanLab","commit_stats":{"total_commits":125,"total_committers":2,"mean_commits":62.5,"dds":0.05600000000000005,"last_synced_commit":"729685837fa3036418f2ae80b177456ee3663f1a"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/Koopman-Laboratory/KoopmanLab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Koopman-Laboratory%2FKoopmanLab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Koopman-Laboratory%2FKoopmanLab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Koopman-Laboratory%2FKoopmanLab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Koopman-Laboratory%2FKoopmanLab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Koopman-Laboratory","download_url":"https://codeload.github.com/Koopman-Laboratory/KoopmanLab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Koopman-Laboratory%2FKoopmanLab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34949234,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-learning","koopman","neural-network","neural-operator","pytorch","scientific-machine-learning"],"created_at":"2026-06-12T19:33:52.165Z","updated_at":"2026-06-30T02:00:30.820Z","avatar_url":"https://github.com/Koopman-Laboratory.png","language":"Python","funding_links":[],"categories":["AI/ML for Simulation"],"sub_categories":["Verified vs declared"],"readme":"\u003ch1 align=\"center\"\u003e\n\u003cimg src=\"https://github.com/Koopman-Laboratory/KoopmanLab/blob/main/logo.png\" width=\"700\"\u003e\n\u003c/h1\u003e\u003cbr\u003e\n\n[![PyPI Version](https://img.shields.io/pypi/v/koopmanlab?color=54B435\u0026label=PyPI)](\nhttps://pypi.org/project/koopmanlab/)\n[![Code Sizez](https://img.shields.io/github/languages/code-size/Koopman-Laboratory/KoopmanLab?label=Code%20Size)](\nhttps://github.com/Koopman-Laboratory/KoopmanLab)\n[![License](https://img.shields.io/pypi/l/koopmanlab?color=FF7000\u0026label=License)](\nhttps://github.com/Koopman-Laboratory/KoopmanLab/blob/main/LICENSE)\n\nKoopmanLab is a package for Koopman Neural Operator with Pytorch.\n\nFor more information, please refer to the following paper, where we provid detailed mathematical derivations, computational designs, and code explanations. \n  - \"[Koopman neural operator as a mesh-free solver of non-linear partial differential equations](https://www.sciencedirect.com/science/article/pii/S0021999124004431).\" Journal of Computational Physics (2024). See also the arXiv preprint arXiv:2301.10022 (2023). \n  - \"[KoopmanLab: machine learning for solving complex physics equations](https://pubs.aip.org/aip/aml/article/1/3/036110/2910717/KoopmanLab-Machine-learning-for-solving-complex).\" APL Machine Learning (2023). \n\n# Installation\nKoopmanLab requires the following dependencies to be installed:\n- PyTorch \u003e= 1.10\n- Numpy \u003e= 1.23.2\n- Matplotlib \u003e= 3.3.2\n\nYou can install KoopmanLab package via the following approaches:\n\n- Install the stable version with `pip`:\n\n```\n$ pip install koopmanlab\n```\n\n- Install the current version by source code with `pip`:\n```\n$ git clone https://github.com/Koopman-Laboratory/KoopmanLab.git\n$ cd KoopmanLab\n$ pip install -e .\n```\n# Quick Start\n\nIf you install KoopmanLab successfully, you can use our model directly by:\n\n``` python\nimport koopmanlab as kp\nencoder = kp.models.encoder_mlp(t_in, operator_size)\ndecoder = kp.models.decoder_mlp(t_in, operator_size)\nKNO1d_model = kp.models.KNO1d(encoder, decoder, operator_size, modes_x = 16, decompose = 6)\n# Input size [batch, x, t_in] Output size [batch, x, t_in] for once iteration\nKNO2d_model = kp.models.KNO2d(encoder, decoder, operator_size, modes_x = 10, modes_y = 10, decompose = 6)\n# Input size [batch, x, t_in] Output size [batch, x, t_in] for once iteration\n```\nIf you do not want to customize the algorithms for training, testing and plotting, we highly recommend that you use our basic APIs to build a Koopman model.\n\n# Usage\nYou can read `demo_ns.py` to learn about some basic APIs and workflow of KoopmanLab. If you want to run `demo_ns.py`, the following data need to be prepared in your computing resource. \n- [Dataset](https://drive.google.com/drive/folders/1UnbQh2WWc6knEHbLn-ZaXrKUZhp7pjt-)\n\nIf you want to generate Navier-Stokes Equation data by yourself, the data generation configuration file can be found in the following link.\n\n- [File](https://github.com/zongyi-li/fourier_neural_operator/tree/master/data_generation/navier_stokes)\n\nOur package provides an easy way to create a Koopman neural operator model.\n``` python\nimport koopmanlab as kp\nMLP_KNO_2D = kp.model.koopman(backbone = \"KNO2d\", autoencoder = \"MLP\", device = device)\nMLP_KNO_2D = kp.model.koopman(backbone = \"KNO2d\", autoencoder = \"MLP\", o = o, m = m, r = r, t_in = 10, device = device)\nMLP_KNO_2D.compile()\n## Parameter definitions:\n# o: the dimension of the learned Koopman operator\n# f: the number of frequency modes below frequency truncation threshold\n# r: the power of the Koopman operator\n# T_in: the duration length of input data\n# device : if CPU or GPU is used for calculating\n\nViT_KNO = kp.model.koopman_vit(decoder = \"MLP\", resolution=(64, 64), patch_size=(2, 2),\n            in_chans=1, out_chans=1, head_num=16, embed_dim=768, depth = 16, parallel = True, high_freq = True, device=device)\nViT_KNO.compile()\n## Parameter definitions:\n# depth: the depth of each head \n# head_num: the number of heads\n# resolution: the spatial resolution of input data\n# patch_size: the size of each patch (i.e., token)\n# in_chans: the number of target variables in the data set\n# out_chans: the number of predicted variables by ViT-KNO , which is usually same as in_chans\n# embed_dim: the embeding dimension\n# parallel: if data parallel is applied\n# high_freq: if high-frequency information complement is applied\n```\nOnce the model is compiled, an optimizer setting is required to run your own experiments. If you want a more customized setting of optimizer and scheduler, you could use any PyTorch method to create them and assign them to Koopman neural operator object, eg. `MLP_KNO_2D.optimizer` and `MLP_KNO_2D.scheduler`.\n``` python\nMLP_KNO_2D.opt_init(\"Adam\", lr = 0.005, step_size=100, gamma=0.5)\n```\nIf you use Burgers equation and Navier-Stokes equation data or the shallow water data provided by PDEBench, there are three specifc data interfaces that you can consider.\n``` python\ntrain_loader, test_loader = kp.data.burgers(path, batch_size = 64, sub = 32)\ntrain_loader, test_loader = kp.data.shallow_water(path, batch_size = 5, T_in = 10, T_out = 40, sub = 1)\ntrain_loader, test_loader = kp.data.navier_stokes(path, batch_size = 10, T_in = 10, T_out = 40, type = \"1e-3\", sub = 1)\n## Parameter definitions:\n# path: the file path of the downloaded data set\n# T_in: the duration length of input data\n# T_out: the duration length required to predict\n# Type: the viscosity coefficient of navier-stokes equation data set.\n# sub: the down-sampling scaling factor. For instance, a scaling factor sub=2 acting on a 2-dimensional data with the spatial resoluion 64*64 will create a down-sampled space of 32*32. The same factor action on a 1 dimensional data with the spatial resoluion 1*64 implies a down-sampled space of 1*32.\n```\nWe recommend that you process your data by PyTorch method `torch.utils.data.DataLoader`. In KNO model, the shape of 2D input data is `[batchsize, x, y, t_len]` and the shape of output data and label is `[batchsize, x, y, T]`, where t_len is defined in `kp.model.koopman` and T is defined in train module. In Koopman-ViT model, the shape of 2D input data is `[batchsize, in_chans, x, y]` and the shape of output data and label is `[batchsize, out_chans, x, y]`.\n\nThe KoopmanLab provides two training and two testing methods of the compact KNO sub-family. If your scenario is single step prediction, you can consider to use `train_single` method or use `train` with `T_out = 1`. Our package provides a method to save and visualize your prediction results in `test`.\n``` python\nMLP_KNO_2D.train_single(epochs=ep, trainloader = train_loader, evalloader = eval_loader)\nMLP_KNO_2D.train(epochs=ep, trainloader = train_loader, evalloader = eval_loader, T_out = T)\nMLP_KNO_2D.test_single(test_loader)\nMLP_KNO_2D.test(test_loader, T_out = T, path = \"./fig/ns_time_error_1e-4/\", is_save = True, is_plot = True)\n```\nAs for the ViT-KNO sub-family, `train` and `test` method is set with a single step predicition scenario. Specifically, `train_multi` and `test_multi` method provide multi-step iteration prediction, where the model iterates `T_out` times in training and testing. \n``` python\nViT_KNO.train_single(epochs=ep, trainloader = train_loader, evalloader = eval_loader)\nViT_KNO.test_single(test_loader)\nViT_KNO.train_multi(epochs=ep, trainloader = train_loader, evalloader = eval_loader, T_out = T_out)\nViT_KNO.test_multi(test_loader)\n## Parameter definitions:\n# epoch: epoch number of training\n# trainloader: dataloader of training, which is returning variable from torch.utils.data.DataLoader\n# evalloader: dataloader of evaluating, which is returning variable from torch.utils.data.DataLoader\n# test_loader: dataloader of testing, which is returning variable from torch.utils.data.DataLoader\n# T_out: the duration length required to predict\n```\nOnce your model has been trained, you can use the saving module provided in KoopmanLab to save your model. Saved variable has three attribute. where `koopman` is the model class variable (i.e., the saved `kno_model` variable), `model` is the trained model variable (i.e., the saved `kno_model.kernel` variable), and `model_params` is the parameters dictionary of trained model variable (i.e., the saved `kno_model.kernel.state_dict()` variable).\n``` python\nMLP_KNO_2D.save(save_path)\n## Parameter definitions:\n# save_path: the file path of the result saving\n```\n# Citation\nIf you use KoopmanLab package for academic research, you are encouraged to cite the following paper:\n```\n@article{xiong2024koopman,\n  title={Koopman neural operator as a mesh-free solver of non-linear partial differential equations},\n  author={Xiong, Wei and Huang, Xiaomeng and Zhang, Ziyang and Deng, Ruixuan and Sun, Pei and Tian, Yang},\n  journal={Journal of Computational Physics},\n  pages={113194},\n  year={2024},\n  publisher={Elsevier}\n}\n\n@article{xiong2023koopmanlab,\n  title={Koopmanlab: machine learning for solving complex physics equations},\n  author={Xiong, Wei and Ma, Muyuan and Huang, Xiaomeng and Zhang, Ziyang and Sun, Pei and Tian, Yang},\n  journal={APL Machine Learning},\n  volume={1},\n  number={3},\n  year={2023},\n  publisher={AIP Publishing}\n}\n```\n# Acknowledgement\nAuthors appreciate Abby, a talented artist, for designing the logo of KoopmanLab.\n\n# License\n[GPL-3.0 License](https://github.com/Koopman-Laboratory/KoopmanLab/blob/main/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKoopman-Laboratory%2FKoopmanLab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FKoopman-Laboratory%2FKoopmanLab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKoopman-Laboratory%2FKoopmanLab/lists"}