非官方 TEOS-10 GSW 海洋学工具箱（Rust版）

适用于微控制器和完整计算机的 GSW

请注意，我们确实遵循 TEOS-10 手册和参考，但此库未获得 TEOS-10 委员会的认可。

开发 GSW-rs 的初始动机是为用于自主海洋学平台（如水下滑翔机和 Argo 浮标）的纯 Rust 固件提供支持。Rust 作为一个理想的选择脱颖而出，因为它具有强大的健壮性和可靠性，辅以集成的测试系统和强大的包管理器来处理依赖关系。我们的 Rust 实现达到了与 C 相当的速度，同时利用 Rust 的明确和直观的语法，使其成为科学应用的优选。

我们已实现了 TEOS-10 中描述的公共函数中的约 53 个，我们确实打算最终涵盖所有这些。在我们完成这项工作的同时，我们将保持一个 清单。

演讲

我们在 2022 年 4 月的 SEA Improving Scientific Software 2022 上介绍了目标和进展（截至 2022 年 4 月），幻灯片在此处提供。

最小支持的 Rust 版本

目前最低支持的 Rust 版本是 1.68.0

安装

此 crate 是作为一个库开发的，因此它打算被其他库或应用程序“导入”。推荐使用 rustup 安装 Rust。有关更多详细信息，请参阅 Rust 编程语言。要将 GSW 包含在其他 crate 中

cargo add gsw

为了确保它在您的平台上正常工作，请克隆此仓库并运行： cargo test 这将编译库并运行所有测试。

功能

从货物手册中：“货物‘功能’提供了一种表达条件编译和可选依赖的机制。”在GSW-rs中定义的功能有

• capi：包含C-API，以便GSW-rs可以像C库一样被访问。例如，可以使用此功能将基于GSW-C的其他GSW实现与GSW-rs链接。
• compat：为了兼容性，复现GSW-Matlab实现。
• invalidasnan：在失败时返回NaN值。默认行为是返回错误。
• nodgdz：忽略重力垂直变化，即与z无关。这在某些数值模型中可能很有用。
• std：激活Rust标准库。默认实现不依赖于std，因此可以在嵌入式系统中运行。

例如，为了与官方Matlab库兼容进行编译

cargo build --features compat

仓库结构

对于任何学习Rust的人来说，这个仓库可能有些令人不知所措。我们在这里做了很多事情，因此有更多文件和目录，这些文件和目录是严格必要的。

• Cargo.toml和src是Rust的基本组件。第一个包含一些描述crate的元数据，而第二个则将源代码分组。这是crate的核心。
  • 请注意，在src中，我们按照TEOS-10库卡片分组模块。我们还隔离了常量，同时避免了重复。
  • src/lib.rs是库的起点。
  • 我们将测试分割，以便它们接近目标函数。通常，所有单元测试都会放在某个地方，但在这里，每个函数都有很多测试，这将增加调试和维护的工作量。此外，我们还添加了科学文献中描述的参考案例。
• 验证测试分组在src外部，在tests中，它使用tests/data中的特别编码验证值（使用convert_refdata）来验证我们的结果。
• convert_refdata是一个辅助crate。我们不打算发布它，因为它仅用于支持GSW-rs。GSW-Matlab提供了一个参考数据集，我们可以使用它来验证我们的库。由于我们的目标是也与微控制器一起工作，因此我们必须以某种方式格式化该数据集，以便它可以在微控制器中使用，从而进行验证。在那里你可以找到它自己的Cargo.toml和src。我们使用postcard进行编码。
• 我们使用FFI公开我们的库，以便它可以在外部作为C库使用。例如，为了测试它，我们用我们的Rust库（GSW-rs）而不是传统的GSW-C链接官方的GSW-Python，并运行Python测试。请查看.github/workflows/gsw-python.yml以了解我们如何将GSW-Python与GSW-rs链接。目录utils、include、assets和examples/usage-from-c都与这一点有关。
• 集成测试在tests中开发，使用在tests/data中特别编码的验证值（使用convert_refdata）来验证我们的结果。请注意，每个模块有一个文件，这些文件足够小，可以适应资源有限的系统的堆栈内存。

许可证

根据3-Clause BSD许可证授权（LICENSE）

贡献

除非您明确声明，否则您根据许可证有意提交的、用于包含在作品中的任何贡献，都应按照上述方式授权，不附加任何额外条款或条件。

贡献应通过GitHub进行，通过分支仓库、创建新分支，并将该新分支推回作为拉取请求。必须包含覆盖新功能或错误修复的测试，如有必要，更新文档。如果您不熟悉此程序，我们鼓励您联系我们，我们将向您介绍整个过程。每个贡献都是有价值的，并将得到认可。

关于测试的说明。我们不遵循将模块的所有测试分组在一起的典型Rust模式。作为一个科学库，特别是大型的库，我们倾向于将测试放在被测试的目标之后，以便于验证某个函数是否覆盖了所需的行为。在可能的情况下，我们还添加了测试以确认文献中描述的特定值。

关于引用的说明：请审阅并添加每个函数的相关文献。验证原始文献中的系数和有效范围尤其重要。

引用

如果您使用此库，我们诚恳地请求您引用以下三个参考文献

Castelao, G.，& Irber, L. (2024). 在Rust中实现的TEOS-10吉布斯海水海洋学工具箱。开源软件杂志，9(93)，5988，https://doi.org/10.21105/joss.05988

@article{Castelao2024,
  doi = {10.21105/joss.05988},
  url = {https://doi.org/10.21105/joss.05988},
  year = {2024},
  publisher = {The Open Journal},
  volume = {9},
  number = {93},
  pages = {5988},
  author = {Guilherme P. Castelao and Luiz Irber},
  title = {Gibbs Sea Water Oceanographic Toolbox of TEOS-10 implemented in Rust},
  journal = {Journal of Open Source Software}
  }

为什么您还应该引用以下两个参考文献？我们非常感谢您通过引用上述参考文献来认可我们开发此库的努力，但我们无法为背后的理论获得任何认可。有一长串出版物导致了库中探索的所有这些关系。虽然我们鼓励您研究并引用与您的工作相关的出版物，但您至少应引用以下两个：总结所有这些出版物的手册56，以及介绍如何使用工具箱的“入门”出版物。

• IOC，SCOR和IAPSO，2010：《国际海水热力学方程-2010：热力学性质的计算和使用》。政府间海洋委员会手册和指南第56号，联合国教科文组织（英文），196页。

• McDougall, T.J.和P.M. Barker，2011：《TEOS-10和吉布斯海水（GSW）海洋学工具箱入门》，28页，SCOR/IAPSO WG127，ISBN 978-0-646-55621-5。

随着我们审阅和扩展此库，我们在每个函数中添加相关的具体参考文献。您可以在我们的源代码或手册中找到这些内容。