{"id":16755221,"url":"https://github.com/castelao/gsw-rs","last_synced_at":"2025-04-03T03:09:54.405Z","repository":{"id":43067563,"uuid":"348212424","full_name":"castelao/GSW-rs","owner":"castelao","description":"Unofficial Gibbs Sea Water Oceanographic Toolbox of TEOS-10 in Rust","archived":false,"fork":false,"pushed_at":"2024-10-28T03:36:13.000Z","size":1431,"stargazers_count":19,"open_issues_count":4,"forks_count":5,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-02T12:43:04.042Z","etag":null,"topics":["data","ocean","ocean-sciences","oceanography","rust"],"latest_commit_sha":null,"homepage":"https://docs.rs/gsw/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/castelao.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2021-03-16T04:24:27.000Z","updated_at":"2025-02-21T02:04:38.000Z","dependencies_parsed_at":"2024-04-25T23:54:17.006Z","dependency_job_id":"98c1a38f-1809-4ef5-b9be-7d3d67304fa6","html_url":"https://github.com/castelao/GSW-rs","commit_stats":{"total_commits":77,"total_committers":6,"mean_commits":"12.833333333333334","dds":"0.24675324675324672","last_synced_commit":"8ffa00f26454ceb9f0967c82d489997ef86c23a4"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/castelao%2FGSW-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/castelao%2FGSW-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/castelao%2FGSW-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/castelao%2FGSW-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/castelao","download_url":"https://codeload.github.com/castelao/GSW-rs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246927835,"owners_count":20856198,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["data","ocean","ocean-sciences","oceanography","rust"],"created_at":"2024-10-13T03:07:06.251Z","updated_at":"2025-04-03T03:09:54.377Z","avatar_url":"https://github.com/castelao.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Unofficial TEOS-10 GSW Oceanographic Toolbox in Rust\n\nGSW for microcontrollers and full computers.\n\nNote that we do follow TEOS-10 manual and references, but this library is not\nendorsed by TEOS-10 committee.\n\nThe initial motivation for developing GSW-rs was to support pure Rust firmware\nfor microcontrollers used in autonomous oceanography platforms -- such as\nunderwater gliders and Argo floats. Rust stands out as an ideal solution due to\nits robustness and reliability complemented by an integrated testing system and\na robust package manager to handle dependencies. Our Rust implementation\nachieves speeds comparable with C while capitalizing on Rust's explicit and\nintuitive syntax which makes it an optimal choice for scientific applications.\n\nWe have already implemented approximately 53 of the public functions described\non TEOS-10, and we do intend to eventually cover all of them. While we're\nworking on that, we'll keep an [inventory list](inventory.md).\n\n## Talks\n\nWe presented about goals and progress (as of Apr 2022) at the\n[SEA Improving Scientific Software 2022](https://sea.ucar.edu/conference/2022),\n[slides available here](https://gsw.castelao.net/talks/).\n\n## Minimum supported Rust version\n\nCurrently the minimum supported Rust version is 1.68.0\n\n## Installing\n\nThis crate was developed as a library, thus it is intended to be 'imported' by\nother libraries or used by applications. The recommended way to install Rust is\nusing [rustup](https://www.rust-lang.org/tools/install). Check the book\n[Rust Programming Language](https://doc.rust-lang.org/book) for more details.\nTo include GSW in another crate:\n```shell\ncargo add gsw\n```\n\nTo be sure it works properly in your platform, clone this repository and run:\n`cargo test`\nwhich will compile the library and run all the tests.\n\n### Features\n\nFrom the Cargo Book: \"Cargo 'features' provide a mechanism to express\nconditional compilation and optional dependencies.\". The features defined in\nGSW-rs are:\n\n- **capi**: Include the C-API so that GSW-rs can be accessed as it was a\n            C-library. For instance, the other GSW implementations based on\n            GSW-C could be linked with GSW-rs instead by using this feature.\n- **compat**: Reproduces the GSW-Matlab implementation for compatibility.\n- **invalidasnan**: Returns NaN values on failure. The default behavior is to\n                    return an error.\n- **nodgdz**: Ignores vertical variations of gravity, i.e. no dependency on z.\n              This might be useful on some numerical models.\n- **std**: Activate the Rust standard library. The default implementation does\n           not rely on std so it can run in embedded systems.\n\nFor example, to compile it compatible with the official Matlab library:\n```shell\ncargo build --features compat\n```\n\n## Repository structure\n\nFor anyone learning Rust, this repository might be overwhelming. We are doing\nmany things here, hence more files and directories that would be strictly\nnecessary.\n\n- The `Cargo.toml` and `src` are the fundamental Rust components. The first\n  one contains some metadata describing the crate, while the second one groups\n  the source code. This is the core of the crate.\n  - Note that in `src` we group the modules following the TEOS-10 library\n    card. We also isolate the constants, while avoiding repetition.\n  - The `src/lib.rs` is the starting point of the library.\n  - We split the tests so that those are close to the target functions. Usually\n    all the unit tests would go together somewhere, but here, each function has\n    so many tests that it would be an extra work to debug and maintain. Also,\n    we add reference cases described in the scientific literature.\n- Validation tests are grouped outside the `src`, in the `tests`, which uses\n  the reference `data`.\n- `convert_refdata` is an auxiliary crate. We don't intend to publish that\n  one since it is only used to support GSW-rs. The GSW-Matlab provides a\n  reference dataset, which we can use to validate our library. Since our goal\n  is to also work with microcontrollers, we have to format that dataset in\n  such a way that it can be used in microcontrollers, thus validated. There\n  you'll find its own `Cargo.toml` and `src`. We use postcard to encode it.\n- We use FFI to expose our library, so it can be used outside as if it was a\n  C-library. For instance, to test it, we link the official GSW-Python with our\n  Rust library (GSW-rs) instead of the traditional GSW-C, and run the Python\n  tests. Take a look on `.github/workflows/gsw-python.yml` to see how we link\n  GSW-Python with GSW-rs. The directories `utils`, `include`, `assets`, and\n  `examples/usage-from-c` are all related to that.\n- Integration tests are developed in `tests`, using the specially encoded\n  verification values (using `convert_refdata`) in `tests/data` to validate\n  our results. Note that there is one file per module, which are small enough\n  to fit in the stack memory of resource-limited systems.\n\n## License\n\nLicensed under the 3-Clause BSD License ([LICENSE](LICENSE))\n\n## Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, as defined in the [LICENSE](LICENSE), shall be\nlicensed as above, without any additional terms or conditions.\n\nContributions should be done through GitHub, by forking the repository,\ncreating a new branch, and pushing that new branch back as a Pull Request.\nTests covering the new feature or bugfix must be included, and if relevant,\nthe documentation updated. If not familiar with the procedure, we encourage to\ncontact us and we will walk you through the process. Every contribution is\nvaluable and will be recognized.\n\nA note on tests. We don't follow the typical Rust pattern of grouping all the\ntests of the module together. As a scientific library, and a large one, we tend\nto keep tests right after the target tested, so it is easy to verify if a\ncertain function covers the desired behavior. Whenever possible, we also add\ntests confirming specific values described in the literature.\n\nA note on references: Please review and add the relevant literature for each\nfunction. It is particularly important to verify the coefficients and the\nvalid range in the original literature.\n\n## Citation\n\nIf you use this library we kindly ask to cite all the three following references:\n\n[![DOI](https://joss.theoj.org/papers/10.21105/joss.05988/status.svg)](https://doi.org/10.21105/joss.05988)\n\nCastelao, G., \u0026 Irber, L. (2024). Gibbs Sea Water Oceanographic Toolbox of\nTEOS-10 implemented in Rust. Journal of Open Source Software, 9(93), 5988,\nhttps://doi.org/10.21105/joss.05988\n\n\n```text\n@article{Castelao2024,\n  doi = {10.21105/joss.05988},\n  url = {https://doi.org/10.21105/joss.05988},\n  year = {2024},\n  publisher = {The Open Journal},\n  volume = {9},\n  number = {93},\n  pages = {5988},\n  author = {Guilherme P. Castelao and Luiz Irber},\n  title = {Gibbs Sea Water Oceanographic Toolbox of TEOS-10 implemented in Rust},\n  journal = {Journal of Open Source Software}\n  }\n```\n\nWhy should you also cite the two following references? We do appreciate\nyou recognizing our efforts developing this library citing the reference\nabove, but we can't take any credit for the theory behind it. There is a\nlong list of publications that resulted in all these relations explored in\nthis library. Although we encourage you to study and cite the ones relevant\nto your work, you should at least cite the two following ones. The manual 56\nthat summarizes all those publications, and the 'Getting started' publication\nwhich presents how to use the Toolbox.\n\n- IOC, SCOR and IAPSO, 2010: The international thermodynamic equation of\n  seawater - 2010: Calculation and use of thermodynamic properties.\n  Intergovernmental - Oceanographic Commission, Manuals and Guides No. 56,\n  UNESCO (English), 196 pp.\n\n- McDougall, T.J. and P.M. Barker, 2011: Getting started with TEOS-10 and the\n  Gibbs Seawater (GSW) Oceanographic Toolbox, 28pp., SCOR/IAPSO WG127,\n  ISBN 978-0-646-55621-5.\n\nAs we review and expand this library, we add the relevant specific references\nwithin each function. You can find those in our source code or the manual.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcastelao%2Fgsw-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcastelao%2Fgsw-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcastelao%2Fgsw-rs/lists"}