GSW-Python

这是基于TEOS-10热力学海水方程（TEOS-10）的Python实现，主要基于GSW-C实现的numpy ufunc包装。这个库取代了原始的python-gsw纯Python实现。进行这种改变的主要原因是通过基于C实现，我们减少了代码冗余，并立即获得了75项方程的更新。
额外的优势包括速度的重大提升、内存使用的减少以及更多功能的加入。代价是需要使用C（或Windows的MSVC C++）编译器从源代码构建包。

警告：仅适用于Python >=3.8。

文档可在以下链接获取：https://teos-10.github.io/GSW-Python/。

对于核心功能，我们使用自动生成的C扩展模块将C函数封装为numpy ufuncs，然后使用自动生成的Python模块添加文档字符串并处理掩码数组。165个仅具有双精度参数和返回值的标量C函数被封装为ufuncs，其中158个在gsw命名空间中暴露，并使用Python中的额外包装器。

一个C函数使用手写的包装器，其他函数则直接在Python中重新实现，而不是进行包装。GSW-Matlab中有但GSW-C中没有的额外函数可能将在Python中重新实现，但并不期望提供所有此类函数。

安装

Pip用户可以使用以下命令安装预构建的wheels：

pip install gsw

conda用户可以在conda-forge中找到二进制文件。

conda install gsw --channel conda-forge

可以使用从repo克隆的方式安装包的开发版本：

pip install .

引用

如果您使用GSW-Python，请引用：McDougall, T.J.和P.M. Barker, 2011：入门TEOS-10和Gibbs海水（GSW）海洋工具箱，28页，SCOR/IAPSO WG127，ISBN 978-0-646-55621-5

@book{mcdougall2011getting,
  author = {McDougall, T. J. and Barker, P. M.},
  title = {Getting started with TEOS-10 and the Gibbs Seawater (GSW) Oceanographic Toolbox},
  year = {2011},
  pages = {28},
  publisher = {SCOR/IAPSO WG127},
  isbn = {978-0-646-55621-5}
}

针对xarray用户的说明

存在一个名为gsw-xarray的gsw包装器，用于xarray。它会在可能的情况下添加CF兼容的属性、单位和名称。

关于生成文档字符串的说明

自动生成的文档字符串在CI中使用codespell进行检查。在自动生成它们时，我们需要运行pre-commit run --all-files并修复发现的文档问题。

开发说明

您需要一个合适的编译器：类Unix系统的gcc或clang，或者在Windows上用于Python本身的MSVC编译器集。对于Windows，已经修改了一些源代码为C++，因为MSVC C编译器不支持原始GSW-C中使用的C99复杂数据类型。

子目录（'tools'）包含用于维护从上游GSW-Matlab和GSW-C repo自动生成的代码的模块和脚本。脚本应从该目录运行；它们对它们所在的位置以及上游repo的位置做出了假设。具体来说，假设GSW-Matlab、GSW-C和GSW-Python git repo都位于同一个基本目录中。

脚本

• copy_from_GSW-C.py：如果后者较新，则从同级的GSW-C repo复制相关的.c和.h文件。
• mat2npz.py：在gsw/tests中生成npz文件，包含来自同级GSW-Matlab repo中gsw_data_v3_0.mat文件的测试数据和检查值。
• make_ufuncs.py：生成src/_ufuncs.c文件，将标量C函数转换为numpy ufuncs。它将在当前目录中写入ufuncs.list，作为ufunc名称的记录。函数根据其签名被识别为ufunc候选者，该签名是从src/c_gsw/gswteos-10.h解析出来的。
• make_wrapped_ufuncs.py：根据make_ufuncs.py的输出生成gsw/_wrapped_ufuncs.py。它添加由Matlab帮助文本构建的文档字符串。
• fix_wrapped_ufunc_typos.py：修复在GSW-Matlab repo中已识别但尚未修复的文档字符串中的错误。
• codegen：运行最后三个Python脚本。

模块

• c_header_parser.py：用于分解gswteos-10.h中函数声明的函数。
• matlab_parser.py：专门用于读取GSW-Matlab函数签名并将帮助文本拆分的函数。
• docstring_parts.py：用于组装文档字符串的文本块。
• docstring_utils.py：用于以numpydoc格式组装文档字符串的函数。
• categories.py：按类别列出gsw函数名称的函数。此函数不用于任何其他函数或脚本，但在最初将函数分类并包含到子模块中时使用。

注意事项

• 除了生成的src/_ufuncs.c之外，还有两个手动编写的C文件：src/method_bodies.c和src/method_def_entries.c。这些文件被src/_ufuncs.c导入。它们处理一些不适合ufuncs的C函数。
• 在gsw/tests/check_functions.py中也进行了专门的Matlab解析，该文件由gsw/tests/test_check_functions.py使用；有关更多信息，请参阅前者的文档字符串。

测试

为了测试，在安装后运行“pytest --pyargs gsw”。