{"id":319912,"name":"Samudra","description":"Efficiently emulates the ocean component of a state-of-the-art climate model, accurately reproducing key ocean variables including sea surface height, horizontal velocities, temperature, and salinity, across their full depth.","url":"https://github.com/suryadheeshjith/samudra","last_synced_at":"2026-04-15T06:02:02.465Z","repository":{"id":267247375,"uuid":"897008418","full_name":"suryadheeshjith/Samudra","owner":"suryadheeshjith","description":"Global Ocean Emulator","archived":false,"fork":false,"pushed_at":"2025-06-22T04:02:06.000Z","size":39458,"stargazers_count":37,"open_issues_count":0,"forks_count":10,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-04T16:58:03.516Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/suryadheeshjith.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-01T20:46:11.000Z","updated_at":"2026-03-23T04:15:30.000Z","dependencies_parsed_at":"2025-07-17T17:29:33.771Z","dependency_job_id":null,"html_url":"https://github.com/suryadheeshjith/Samudra","commit_stats":null,"previous_names":["m2lines/samudra","suryadheeshjith/samudra"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/suryadheeshjith/Samudra","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/suryadheeshjith%2FSamudra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/suryadheeshjith%2FSamudra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/suryadheeshjith%2FSamudra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/suryadheeshjith%2FSamudra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/suryadheeshjith","download_url":"https://codeload.github.com/suryadheeshjith/Samudra/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/suryadheeshjith%2FSamudra/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31668050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T17:19:37.612Z","status":"online","status_checked_at":"2026-04-11T02:00:05.776Z","response_time":54,"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"}},"owner":{"login":"suryadheeshjith","name":"Surya Dheeshjith","uuid":"41594351","kind":"user","description":"","email":"","website":"http://suryadheeshjith.github.io/","location":"Bangalore, India","twitter":null,"company":null,"icon_url":"https://avatars.githubusercontent.com/u/41594351?u=65807bc70b6c7720d9adaa7bb9cf533760b5f5a4\u0026v=4","repositories_count":5,"last_synced_at":"2023-03-08T22:52:52.136Z","metadata":{"has_sponsors_listing":false},"html_url":"https://github.com/suryadheeshjith","funding_links":[],"total_stars":null,"followers":null,"following":null,"created_at":"2022-11-18T12:42:06.845Z","updated_at":"2023-03-08T22:52:52.149Z","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/suryadheeshjith","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/suryadheeshjith/repositories"},"packages":[],"commits":{"id":10527273,"full_name":"suryadheeshjith/samudra","default_branch":"main","total_commits":25,"total_committers":1,"total_bot_commits":0,"total_bot_committers":0,"mean_commits":25.0,"dds":0.0,"past_year_total_commits":1,"past_year_total_committers":1,"past_year_total_bot_commits":0,"past_year_total_bot_committers":0,"past_year_mean_commits":1.0,"past_year_dds":0.0,"last_synced_at":"2026-04-13T05:02:02.097Z","last_synced_commit":"0eb8877f2f5cae7b1e9b55cae98bb5c3459d8574","created_at":"2025-07-03T00:19:47.957Z","updated_at":"2026-04-13T05:02:02.077Z","committers":[{"name":"Surya","email":"surya.dheeshjith@gmail.com","login":"suryadheeshjith","count":25}],"past_year_committers":[{"name":"Surya Dheeshjith","email":"41594351+suryadheeshjith","login":"suryadheeshjith","count":1}],"commits_url":"https://commits.ecosyste.ms/api/v1/hosts/GitHub/repositories/suryadheeshjith%2Fsamudra/commits","host":{"name":"GitHub","url":"https://github.com","kind":"github","last_synced_at":"2026-04-15T00:00:09.512Z","repositories_count":6213601,"commits_count":903369938,"contributors_count":34924460,"owners_count":1144568,"icon_url":"https://github.com/github.png","host_url":"https://commits.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://commits.ecosyste.ms/api/v1/hosts/GitHub/repositories"}},"issues_stats":{"full_name":"suryadheeshjith/samudra","html_url":"https://github.com/suryadheeshjith/samudra","last_synced_at":"2026-04-13T05:02:09.942Z","status":"error","issues_count":1,"pull_requests_count":6,"avg_time_to_close_issue":2512463.0,"avg_time_to_close_pull_request":418771.0,"issues_closed_count":1,"pull_requests_closed_count":6,"pull_request_authors_count":2,"issue_authors_count":1,"avg_comments_per_issue":2.0,"avg_comments_per_pull_request":0.16666666666666666,"merged_pull_requests_count":4,"bot_issues_count":0,"bot_pull_requests_count":0,"past_year_issues_count":1,"past_year_pull_requests_count":6,"past_year_avg_time_to_close_issue":2512463.0,"past_year_avg_time_to_close_pull_request":418771.0,"past_year_issues_closed_count":1,"past_year_pull_requests_closed_count":6,"past_year_pull_request_authors_count":2,"past_year_issue_authors_count":1,"past_year_avg_comments_per_issue":2.0,"past_year_avg_comments_per_pull_request":0.16666666666666666,"past_year_bot_issues_count":0,"past_year_bot_pull_requests_count":0,"past_year_merged_pull_requests_count":4,"created_at":"2025-07-03T00:19:48.954Z","updated_at":"2026-04-13T05:02:09.942Z","repository_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/repositories/suryadheeshjith%2Fsamudra","issues_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/repositories/suryadheeshjith%2Fsamudra/issues","issue_labels_count":{},"pull_request_labels_count":{},"issue_author_associations_count":{},"pull_request_author_associations_count":{"OWNER":8},"issue_authors":{},"pull_request_authors":{"suryadheeshjith":8},"host":{"name":"GitHub","url":"https://github.com","kind":"github","last_synced_at":"2026-04-15T00:00:09.535Z","repositories_count":14268221,"issues_count":34624750,"pull_requests_count":113266696,"authors_count":11234925,"icon_url":"https://github.com/github.png","host_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/repositories","owners_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/owners","authors_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/authors"},"past_year_issue_labels_count":{},"past_year_pull_request_labels_count":{},"past_year_issue_author_associations_count":{},"past_year_pull_request_author_associations_count":{},"past_year_issue_authors":{},"past_year_pull_request_authors":{},"maintainers":[{"login":"suryadheeshjith","count":8,"url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/authors/suryadheeshjith"}],"active_maintainers":[]},"events":{"total":{"ReleaseEvent":1,"DeleteEvent":6,"PullRequestEvent":10,"ForkEvent":4,"WatchEvent":4,"IssueCommentEvent":1,"PushEvent":33,"CreateEvent":8},"last_year":{"ForkEvent":2,"WatchEvent":4,"PushEvent":1}},"keywords":[],"dependencies":[{"ecosystem":"actions","filepath":".github/workflows/pre-commit.yml","sha":null,"kind":"manifest","created_at":"2025-03-17T08:41:48.553Z","updated_at":"2025-03-17T08:41:48.553Z","repository_link":"https://github.com/suryadheeshjith/Samudra/blob/main/.github/workflows/pre-commit.yml","dependencies":[{"id":22298356524,"package_name":"actions/checkout","ecosystem":"actions","requirements":"v2","direct":true,"kind":"composite","optional":false},{"id":22298356525,"package_name":"actions/setup-python","ecosystem":"actions","requirements":"v2","direct":true,"kind":"composite","optional":false}]},{"ecosystem":"pypi","filepath":"pyproject.toml","sha":null,"kind":"manifest","created_at":"2025-03-17T08:41:48.686Z","updated_at":"2025-03-17T08:41:48.686Z","repository_link":"https://github.com/suryadheeshjith/Samudra/blob/main/pyproject.toml","dependencies":[{"id":22298356528,"package_name":"aiohttp","ecosystem":"pypi","requirements":"==3.9.3","direct":true,"kind":"runtime","optional":false},{"id":22298356529,"package_name":"cartopy","ecosystem":"pypi","requirements":"==0.23","direct":true,"kind":"runtime","optional":false},{"id":22298356530,"package_name":"cftime","ecosystem":"pypi","requirements":"\u003e=1.5.2","direct":true,"kind":"runtime","optional":false},{"id":22298356531,"package_name":"cmocean","ecosystem":"pypi","requirements":"==4.0.3","direct":true,"kind":"runtime","optional":false},{"id":22298358819,"package_name":"dacite","ecosystem":"pypi","requirements":"==1.9.1","direct":true,"kind":"runtime","optional":false},{"id":22298358820,"package_name":"dask","ecosystem":"pypi","requirements":"==2024.2.1","direct":true,"kind":"runtime","optional":false},{"id":22298358821,"package_name":"einops","ecosystem":"pypi","requirements":"==0.8","direct":true,"kind":"runtime","optional":false},{"id":22298358822,"package_name":"huggingface-hub","ecosystem":"pypi","requirements":"==0.23.4","direct":true,"kind":"runtime","optional":false},{"id":22298358823,"package_name":"ipykernel","ecosystem":"pypi","requirements":"==6.29.3","direct":true,"kind":"runtime","optional":false},{"id":22298358824,"package_name":"ipywidgets","ecosystem":"pypi","requirements":"==8.1.2","direct":true,"kind":"runtime","optional":false},{"id":22298358825,"package_name":"matplotlib","ecosystem":"pypi","requirements":"==3.8.3","direct":true,"kind":"runtime","optional":false},{"id":22298358826,"package_name":"nc-time-axis","ecosystem":"pypi","requirements":"==1.4.1","direct":true,"kind":"runtime","optional":false},{"id":22298359369,"package_name":"numpy","ecosystem":"pypi","requirements":"==1.24.4","direct":true,"kind":"runtime","optional":false},{"id":22298359370,"package_name":"pandas","ecosystem":"pypi","requirements":"==2.2.1","direct":true,"kind":"runtime","optional":false},{"id":22298359371,"package_name":"requests","ecosystem":"pypi","requirements":"==2.32.3","direct":true,"kind":"runtime","optional":false},{"id":22298359372,"package_name":"scikit-learn","ecosystem":"pypi","requirements":"==1.4.1.post1","direct":true,"kind":"runtime","optional":false},{"id":22298359373,"package_name":"torch","ecosystem":"pypi","requirements":"==2.2.1","direct":true,"kind":"runtime","optional":false},{"id":22298359374,"package_name":"xarray","ecosystem":"pypi","requirements":"==2023.7","direct":true,"kind":"runtime","optional":false},{"id":22298359375,"package_name":"xarrayutils","ecosystem":"pypi","requirements":"==2.0.1","direct":true,"kind":"runtime","optional":false},{"id":22298360245,"package_name":"zarr","ecosystem":"pypi","requirements":"==2.16.1","direct":true,"kind":"runtime","optional":false}]},{"ecosystem":"pypi","filepath":"environment.yml","sha":null,"kind":"manifest","created_at":"2025-07-17T17:29:27.291Z","updated_at":"2025-07-17T17:29:27.291Z","repository_link":"https://github.com/suryadheeshjith/Samudra/blob/main/environment.yml","dependencies":[{"id":24175486987,"package_name":"numpy","ecosystem":"pypi","requirements":"==1.24.4","direct":true,"kind":"runtime","optional":false},{"id":24175487093,"package_name":"matplotlib","ecosystem":"pypi","requirements":"==3.8.3","direct":true,"kind":"runtime","optional":false},{"id":24175487094,"package_name":"xarray","ecosystem":"pypi","requirements":"==2023.7.0","direct":true,"kind":"runtime","optional":false},{"id":24175487095,"package_name":"zarr","ecosystem":"pypi","requirements":"==2.16.1","direct":true,"kind":"runtime","optional":false},{"id":24175487262,"package_name":"ipykernel","ecosystem":"pypi","requirements":"==6.29.3","direct":true,"kind":"runtime","optional":false},{"id":24175487263,"package_name":"cartopy","ecosystem":"pypi","requirements":"==0.23.0","direct":true,"kind":"runtime","optional":false},{"id":24175487359,"package_name":"xarrayutils","ecosystem":"pypi","requirements":"==2.0.1","direct":true,"kind":"runtime","optional":false},{"id":24175487402,"package_name":"dacite","ecosystem":"pypi","requirements":"==1.9.1","direct":true,"kind":"runtime","optional":false},{"id":24175487403,"package_name":"dask","ecosystem":"pypi","requirements":"==2024.2.1","direct":true,"kind":"runtime","optional":false},{"id":24175487404,"package_name":"pandas","ecosystem":"pypi","requirements":"==2.2.1","direct":true,"kind":"runtime","optional":false},{"id":24175487405,"package_name":"cmocean","ecosystem":"pypi","requirements":"==4.0.3","direct":true,"kind":"runtime","optional":false},{"id":24175487418,"package_name":"torch","ecosystem":"pypi","requirements":"==2.2.1","direct":true,"kind":"runtime","optional":false},{"id":24175487419,"package_name":"scikit-learn","ecosystem":"pypi","requirements":"==1.4.1.post1","direct":true,"kind":"runtime","optional":false},{"id":24175487420,"package_name":"huggingface-hub","ecosystem":"pypi","requirements":"==0.23.4","direct":true,"kind":"runtime","optional":false},{"id":24175487421,"package_name":"ipywidgets","ecosystem":"pypi","requirements":"==8.1.2","direct":true,"kind":"runtime","optional":false},{"id":24175487422,"package_name":"requests","ecosystem":"pypi","requirements":"==2.32.3","direct":true,"kind":"runtime","optional":false},{"id":24175487423,"package_name":"aiohttp","ecosystem":"pypi","requirements":"==3.9.3","direct":true,"kind":"runtime","optional":false},{"id":24175487424,"package_name":"cftime","ecosystem":"pypi","requirements":"\u003e=1.5.2","direct":true,"kind":"runtime","optional":false},{"id":24175487425,"package_name":"einops","ecosystem":"pypi","requirements":"==0.8.0","direct":true,"kind":"runtime","optional":false},{"id":24175487426,"package_name":"nc-time-axis","ecosystem":"pypi","requirements":"==1.4.1","direct":true,"kind":"runtime","optional":false}]}],"score":3.6109179126442243,"created_at":"2025-07-03T00:19:42.119Z","updated_at":"2026-04-15T06:02:02.467Z","avatar_url":"https://github.com/suryadheeshjith.png","language":"Jupyter Notebook","category":"Hydrosphere","sub_category":"Ocean Models","monthly_downloads":0,"total_dependent_repos":0,"total_dependent_packages":0,"readme":"# Samudra: A Global Ocean Emulator\n\nThis repository contains the implementation of Samudra, a global ocean emulator described in [\"Samudra: An AI Global Ocean Emulator for Climate\"](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2024GL114318). Samudra efficiently emulates the ocean component of a state-of-the-art climate model, accurately reproducing key ocean variables including sea surface height, horizontal velocities, temperature, and salinity, across their full depth.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"/assets/globe.gif\" \u003e\n\u003c/p\u003e\n\n## Overview\n\nSamudra reproduces the 3D ocean temperature structure and variability of the OM4 climate model with high fidelity, while also demonstrating stable long-term performance under realistic, time-varying forcing conditions. It achieves a significant speedup as well—rolling out a 100-year simulation is approximately 150 times faster than the original model.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"/assets/enso.gif\" \u003e\n\u003c/p\u003e\n\n## Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/suryadheeshjith/Samudra.git\ncd Samudra\n```\n\n2. Set up the environment using either method:\n\nUsing conda:\n```bash\nconda env create -f environment.yml\nconda activate samudra\n```\n\nUsing [`uv`](https://docs.astral.sh/uv/):\n```bash\nuv sync\nsource .venv/bin/activate\n```\n\n## Usage\n\nTo train or rollout Samudra, download the OM4 data and statistics referenced in the [OM4 Data](#om4-data) section. You can also substitute your own data, provided it aligns with the same format. Note that mean and standard deviation files are precomputed for training and model rollouts; if you opt to use your own data, you will need to compute these statistics yourself.\n\nShould you wish to evaluate Samudra directly, you may use the pre-trained model weights discussed in the [Trained Model Weights](#trained-model-weights) section.\n\n### Training\nA default training configuration is provided in the file configs/train_samudra_om4.yaml. Update all fields marked with # FILL IN to reference your local data paths and files for OM4 data and statistics.\n\n\u003e Note: Ensure your environment is activated before training.\n```bash\n# Train a new model\ntorchrun src/train.py --config path/to/train_config.yaml\n```\n\n### Rollout\nA default rollout configuration is provided in configs/rollout_samudra_om4.yaml. Update all fields marked with # FILL IN to reference your local data paths and files for OM4 data and statistics.\n\n\u003e Note: Ensure your environment is activated before training.\n```bash\n# Produce a rollout from a trained model (and optionally save the result)\npython src/rollout.py --config path/to/rollout_config.yaml --ckpt_path path/to/checkpoint.pt --save_zarr\n```\n\n\u003e Note: For both training and rollout, you may change the experiment name in the config files or use `--sub_name` argument in the command line to specify a different name for the output directory.\n\n## OM4 Data\nThe OM4 data and corresponding statistics are publicly available as Zarr files via our hosted pod.\n\n```python\nimport xarray as xr\n\n# Download statistics\nmeans = xr.open_dataset(\"https://nyu1.osn.mghpcc.org/m2lines-pubs/Samudra/OM4_means\", engine='zarr', chunks={})\nmeans.to_zarr(\"local/path/to/data-dir/means.zarr\")\n\nstds = xr.open_dataset(\"https://nyu1.osn.mghpcc.org/m2lines-pubs/Samudra/OM4_stds\", engine='zarr', chunks={})\nstds.to_zarr(\"local/path/to/data-dir/stds.zarr\")\n```\n\nDownloading the entire dataset (~70 GB) can be time-consuming, depending on your network speed. If you only need to evaluate Samudra on the test set, a reduced dataset (~12 GB) is sufficient.\n\n```python\nimport xarray as xr\n\n# Download the entire data\ndata = xr.open_dataset(\"https://nyu1.osn.mghpcc.org/m2lines-pubs/Samudra/OM4\", engine='zarr', chunks={})\n\n# For training ~ 70GB\ndata.to_zarr(\"local/path/to/data-dir/data.zarr\")\n\n# (OR) For evaluation ~ 12GB\ndata.sel(time=slice(\"2014-10-10\", \"2022-12-24\")).to_zarr(\"local/path/to/data-dir/data.zarr\")\n```\n\n## Trained Model Weights\nPre-trained weights for Samudra are available on [Hugging Face](https://huggingface.co/M2LInES/Samudra). You can download them as follows:\n```bash\n# Download the weights for thermo model\nwget https://huggingface.co/M2LInES/Samudra/resolve/main/samudra_thermo_seed1.pt\n\n# (OR) Download the weights for thermo-dynamic model\nwget https://huggingface.co/M2LInES/Samudra/resolve/main/samudra_thermo_dynamic_seed1.pt\n```\n\nThere are 5 seeds saved for each model.\n\n## Paper Plots\nThe notebooks in the `notebooks` folder reproduce most of the plots from the paper.\n\nFurther methodological details and model architecture specifications can be found in the [paper](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2024GL114318).\n\n## Citation\n\nIf you find this code useful in your research, please cite:\n```\n@article{dheeshjith2025samudra,\n  title={Samudra: An ai global ocean emulator for climate},\n  author={Dheeshjith, Surya and Subel, Adam and Adcroft, Alistair and Busecke, Julius and Fernandez-Granda, Carlos and Gupta, Shubham and Zanna, Laure},\n  journal={Geophysical Research Letters},\n  volume={52},\n  number={10},\n  pages={e2024GL114318},\n  year={2025},\n  publisher={Wiley Online Library}\n}\n```\n","funding_links":[],"readme_doi_urls":[],"works":{},"citation_counts":{},"total_citations":0,"keywords_from_contributors":[],"project_url":"https://ost.ecosyste.ms/api/v1/projects/319912","html_url":"https://ost.ecosyste.ms/projects/319912"}