fast-gsw 0.2.0__tar.gz

fast_gsw-0.2.0/LICENSE

@@ -0,0 +1,73 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  This is the full text of the GNU General Public License, version 3.
+The complete license text, including all seventeen numbered sections,
+the definitions, and both appendices ("How to Apply These Terms to Your
+New Programs" and the disclaimer of warranty), is available from the
+Free Software Foundation at:
+
+    https://www.gnu.org/licenses/gpl-3.0.txt
+
+This project is distributed under the terms of that license. A copy of
+the full, canonical license text should accompany this distribution;
+if it does not, you can obtain one from the URL above or by writing to:
+
+    Free Software Foundation, Inc.
+    51 Franklin Street, Fifth Floor
+    Boston, MA 02110-1301, USA
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    fast_gsw
+    Copyright (C) Lucas Merckelbach
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.

fast_gsw-0.2.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+recursive-include src/fast_gsw/_csrc *.c *.h
+include src/fast_gsw/_csrc/LICENSE

fast_gsw-0.2.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: fast_gsw
+Version: 0.2.0
+Summary: Fast ctypes-based implementation of some gsw (TEOS-10) functions for vectorized CTD processing
+Author-email: Lucas Merckelbach <lucas.merckelbach@hereon.de>
+License-Expression: GPL-3.0-or-later
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Dynamic: license-file
+
+# fast_gsw
+
+A ctypes-based Python interface for fast, vectorized execution of a few
+[TEOS-10 GSW](http://www.teos-10.org/) (Gibbs SeaWater) oceanographic
+functions, intended for processing large arrays of CTD
+(conductivity/temperature/pressure) data, such as from ocean gliders.
+
+Currently implemented:
+
+- `rho(C, t, P, lon, lat)` — in-situ density
+- `pot_rho(C, t, P, lon, lat)` — potential density (reference pressure 0 dbar)
+- `SA(C, t, P, lon, lat)` — absolute salinity
+- `CT(C, t, P, lon, lat)` — conservative temperature
+
+All inputs/outputs are plain numpy arrays (scalars are broadcast); units are
+conductivity in mS/cm, temperature in °C, pressure in dbar, and longitude /
+latitude in decimal degrees.
+
+## Why
+
+The pure-Python [`gsw`](https://pypi.org/project/gsw/) package computes
+in-situ density (and similar derived quantities) as a chain of several
+composed Python function calls per array (e.g.
+`SP_from_C -> SA_from_SP -> rho_t_exact`). For large arrays of CTD triplets,
+`fast_gsw` collapses that whole pipeline into a single C function call by
+vendoring and compiling the TEOS-10 C implementation and calling it via
+`ctypes`, which removes the Python-level per-step call overhead.
+
+## Install
+
+```
+pip install fast_gsw
+```
+
+This compiles the vendored TEOS-10 C sources at install time, so a C
+compiler (gcc/clang) must be available. No other manual steps, root access,
+or system-wide library installation are required.
+
+To install from a local checkout:
+
+```
+pip install .
+```
+
+## License
+
+`fast_gsw` itself is licensed under the GPLv3 (see `LICENSE`). It vendors and
+compiles source code from the [TEOS-10 GSW-C](https://github.com/TEOS-10/GSW-C)
+Oceanographic Toolbox, C version 3.06.16, under the license in
+`src/fast_gsw/_csrc/LICENSE`.

fast_gsw-0.2.0/README.md

@@ -0,0 +1,50 @@
+# fast_gsw
+
+A ctypes-based Python interface for fast, vectorized execution of a few
+[TEOS-10 GSW](http://www.teos-10.org/) (Gibbs SeaWater) oceanographic
+functions, intended for processing large arrays of CTD
+(conductivity/temperature/pressure) data, such as from ocean gliders.
+
+Currently implemented:
+
+- `rho(C, t, P, lon, lat)` — in-situ density
+- `pot_rho(C, t, P, lon, lat)` — potential density (reference pressure 0 dbar)
+- `SA(C, t, P, lon, lat)` — absolute salinity
+- `CT(C, t, P, lon, lat)` — conservative temperature
+
+All inputs/outputs are plain numpy arrays (scalars are broadcast); units are
+conductivity in mS/cm, temperature in °C, pressure in dbar, and longitude /
+latitude in decimal degrees.
+
+## Why
+
+The pure-Python [`gsw`](https://pypi.org/project/gsw/) package computes
+in-situ density (and similar derived quantities) as a chain of several
+composed Python function calls per array (e.g.
+`SP_from_C -> SA_from_SP -> rho_t_exact`). For large arrays of CTD triplets,
+`fast_gsw` collapses that whole pipeline into a single C function call by
+vendoring and compiling the TEOS-10 C implementation and calling it via
+`ctypes`, which removes the Python-level per-step call overhead.
+
+## Install
+
+```
+pip install fast_gsw
+```
+
+This compiles the vendored TEOS-10 C sources at install time, so a C
+compiler (gcc/clang) must be available. No other manual steps, root access,
+or system-wide library installation are required.
+
+To install from a local checkout:
+
+```
+pip install .
+```
+
+## License
+
+`fast_gsw` itself is licensed under the GPLv3 (see `LICENSE`). It vendors and
+compiles source code from the [TEOS-10 GSW-C](https://github.com/TEOS-10/GSW-C)
+Oceanographic Toolbox, C version 3.06.16, under the license in
+`src/fast_gsw/_csrc/LICENSE`.

fast_gsw-0.2.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fast_gsw"
+version = "0.2.0"
+description = "Fast ctypes-based implementation of some gsw (TEOS-10) functions for vectorized CTD processing"
+readme = "README.md"
+license = "GPL-3.0-or-later"
+authors = [{ name = "Lucas Merckelbach", email = "lucas.merckelbach@hereon.de" }]
+requires-python = ">=3.9"
+dependencies = ["numpy"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: POSIX",
+    "Programming Language :: Python",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+zip-safe = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[dependency-groups]
+dev = [
+    "gsw>=3.6.20",
+    "ipython>=8.18.1",
+    "pytest>=8.4.2",
+    "setuptools>=82.0.1",
+]

fast_gsw-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fast_gsw-0.2.0/setup.py

@@ -0,0 +1,62 @@
+import os
+import sys
+
+from setuptools import Extension, setup
+from setuptools.command.build_ext import build_ext as _build_ext
+
+CSRC = os.path.join("src", "fast_gsw", "_csrc")
+SOURCES = [
+    os.path.join(CSRC, "gsw_oceanographic_toolbox.c"),
+    os.path.join(CSRC, "gsw_saar.c"),
+    os.path.join(CSRC, "gsw_vector.c"),
+]
+
+
+class ctypes_build_ext(_build_ext):
+    """Build a plain shared library (no CPython C-API) for loading via
+    ctypes.CDLL, named like a normal shared object rather than an
+    importable CPython extension module.
+    """
+
+    def get_export_symbols(self, ext):
+        return []
+
+    def get_ext_filename(self, ext_name):
+        parts = ext_name.split(".")
+        if sys.platform.startswith("linux"):
+            return os.path.join(*parts) + ".so"
+        elif sys.platform == "darwin":
+            return os.path.join(*parts) + ".dylib"
+        elif sys.platform == "win32":
+            return os.path.join(*parts) + ".dll"
+        return super().get_ext_filename(ext_name)
+
+    def build_extension(self, ext):
+        objects = self.compiler.compile(
+            ext.sources,
+            output_dir=self.build_temp,
+            include_dirs=ext.include_dirs,
+            extra_postargs=ext.extra_compile_args,
+        )
+        ext_path = self.get_ext_fullpath(ext.name)
+        os.makedirs(os.path.dirname(ext_path), exist_ok=True)
+        self.compiler.link_shared_object(
+            objects,
+            ext_path,
+            libraries=ext.libraries,
+            extra_postargs=ext.extra_link_args,
+        )
+
+
+libgsw_vector = Extension(
+    "fast_gsw.libgsw_vector",
+    sources=SOURCES,
+    include_dirs=[CSRC],
+    libraries=["m"],
+    extra_compile_args=["-O3", "-fPIC"],
+)
+
+setup(
+    ext_modules=[libgsw_vector],
+    cmdclass={"build_ext": ctypes_build_ext},
+)

fast_gsw-0.2.0/src/fast_gsw/__init__.py

@@ -0,0 +1,165 @@
+import ctypes
+import glob
+import os
+
+import numpy as np
+
+_pkg_dir = os.path.dirname(os.path.abspath(__file__))
+_candidates = glob.glob(os.path.join(_pkg_dir, "libgsw_vector*"))
+if not _candidates:
+    raise ImportError(
+        "Could not locate the compiled libgsw_vector shared library inside "
+        f"the fast_gsw package directory ({_pkg_dir}); was fast_gsw installed "
+        "correctly (pip install .)?"
+    )
+libgsw=ctypes.CDLL(_candidates[0])
+
+## return and argument declarations.
+libgsw.gsw_vector_rho.restype=ctypes.c_void_p
+libgsw.gsw_vector_rho.argtypes=(ctypes.POINTER(ctypes.c_double),
+                                ctypes.POINTER(ctypes.c_double),
+                                ctypes.POINTER(ctypes.c_double),
+                                ctypes.POINTER(ctypes.c_double),
+                                ctypes.POINTER(ctypes.c_double),
+                                ctypes.c_uint,
+                                ctypes.POINTER(ctypes.c_double))
+
+libgsw.gsw_vector_pot_rho.restype=ctypes.c_void_p
+libgsw.gsw_vector_pot_rho.argtypes=(ctypes.POINTER(ctypes.c_double),
+                                    ctypes.POINTER(ctypes.c_double),
+                                    ctypes.POINTER(ctypes.c_double),
+                                    ctypes.POINTER(ctypes.c_double),
+                                    ctypes.POINTER(ctypes.c_double),
+                                    ctypes.c_uint,
+                                    ctypes.POINTER(ctypes.c_double))
+
+
+libgsw.gsw_vector_SA.restype=ctypes.c_void_p
+libgsw.gsw_vector_SA.argtypes=(ctypes.POINTER(ctypes.c_double),
+                                ctypes.POINTER(ctypes.c_double),
+                                ctypes.POINTER(ctypes.c_double),
+                                ctypes.POINTER(ctypes.c_double),
+                                ctypes.POINTER(ctypes.c_double),
+                                ctypes.c_uint,
+                                ctypes.POINTER(ctypes.c_double))
+
+libgsw.gsw_vector_CT.restype=ctypes.c_void_p
+libgsw.gsw_vector_CT.argtypes=(ctypes.POINTER(ctypes.c_double),
+                                ctypes.POINTER(ctypes.c_double),
+                                ctypes.POINTER(ctypes.c_double),
+                                ctypes.POINTER(ctypes.c_double),
+                                ctypes.POINTER(ctypes.c_double),
+                                ctypes.c_uint,
+                                ctypes.POINTER(ctypes.c_double))
+
+class Caller(object):
+
+    def __call__(self,libgsw_vector_fun,C,t,P,lon,lat):
+        return self.call_function(libgsw_vector_fun,C,t,P,lon,lat)
+    
+    def is_iterable(self,x):
+        ''' see if a parameter is iterable '''
+        try:
+            (_x for _x in x)
+            return True
+        except TypeError:
+            return False
+
+    def cast_arguments(self,*p):
+        ''' casts all arguments into double arrays.
+
+        Not intended to be called directly.
+        '''
+        pm=[]
+        plist=[self.is_iterable(_p) for _p in p]
+        s=[len(_p) for _p,_pl in zip(p,plist) if _pl]
+        if not all([_s==s[0] for _s in s]):
+            raise ValueError("Not all vectors are equally long.")
+        for i,(_p,_pl) in enumerate(zip(p,plist)):
+            if not _pl:
+                pm.append(np.array([_p]*s[0]).astype(float))
+            else:
+                try:
+                    if _p.dtype!=np.float64:
+                        pm.append(_p.astype('float'))
+                    else:
+                        pm.append(_p)
+                except AttributeError:
+                    pm.append(np.array(_p).astype('float'))
+        return s[0],pm
+
+    def call_function(self,libgsw_vector_fun,C,t,P,lon,lat):
+        n,(C,t,P,lon,lat)=self.cast_arguments(C,t,P,lon,lat)
+        x=np.zeros(n,float)
+        libgsw_vector_fun(C.ctypes.data_as(ctypes.POINTER(ctypes.c_double)),
+                          t.ctypes.data_as(ctypes.POINTER(ctypes.c_double)),
+                          P.ctypes.data_as(ctypes.POINTER(ctypes.c_double)),
+                          lon.ctypes.data_as(ctypes.POINTER(ctypes.c_double)),
+                          lat.ctypes.data_as(ctypes.POINTER(ctypes.c_double)),
+                          n,
+                          x.ctypes.data_as(ctypes.POINTER(ctypes.c_double)))
+        return x
+
+__caller=Caller()
+    
+def rho(C,t,P,lon,lat):
+    '''
+    Calculates in situ density of seawater from conductivity, in-situ temperature and pressure,
+    and lat/lon.
+
+    C conductivity: mS/cm
+    t in-situ temperature: deg C
+    P pressure: dbar
+
+    lon longitude: decimal degrees
+    lat latitude: decimal degrees
+
+    '''
+    return __caller(libgsw.gsw_vector_rho,C,t,P,lon,lat)
+
+
+def pot_rho(C,t,P,lon,lat):
+    '''
+    Calculates in potential density of seawater from conductivity, in-situ temperature and pressure,
+    and lat/lon.
+
+    C conductivity: mS/cm
+    t in-situ temperature: deg C
+    P pressure: dbar
+
+    lon longitude: decimal degrees
+    lat latitude: decimal degrees
+
+    '''
+    return __caller(libgsw.gsw_vector_pot_rho,C,t,P,lon,lat)
+
+
+def CT(C,t,P,lon,lat):
+    '''
+    Calculates in conservative temperature from conductivity, in-situ temperature,pressure,
+    and lat/lon.
+
+    C conductivity: mS/cm
+    t in-situ temperature: deg C
+    P pressure: dbar
+
+    lon longitude: decimal degrees
+    lat latitude: decimal degrees
+
+    '''
+    return __caller(libgsw.gsw_vector_CT,C,t,P,lon,lat)
+
+def SA(C,t,P,lon,lat):
+    ''' returns absolute salinity
+
+    C conductivity: mS/cm
+    t in-situ temperature: deg C
+    P pressure: dbar
+
+    lon longitude: decimal degrees
+    lat latitude: decimal degrees
+
+    '''
+    return __caller(libgsw.gsw_vector_SA,C,t,P,lon,lat)
+
+

fast_gsw-0.2.0/src/fast_gsw/_csrc/LICENSE

@@ -0,0 +1,34 @@
+Licence for the use of the Gibbs SeaWater (GSW) Oceanographic Toolbox
+
+Copyright (c) 2011, SCOR/IAPSO WG127 (Scientific Committee on Oceanic Research/
+International Association for the Physical Sciences of the Oceans, Working Group 127).
+
+All rights reserved.
+
+Redistribution and use, in source and binary forms, without modification, is permitted
+provided that the following conditions are met:
+
+• Redistributions of source code must retain the above copyright notice, this list
+  of conditions and the following disclaimer.
+
+• Redistributions in binary form must reproduce the above copyright notice, this
+  list of conditions and the following disclaimer in the documentation and/or other
+  materials provided with the distribution.
+
+• Neither the name of SCOR/IAPSO WG127 nor the names of its contributors may be used
+  to endorse or promote products derived from this software without specific prior
+  written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
+SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGE.
+
+The software is available from http://www.TEOS-10.org
+