|PyPI version| |Docs badge| |License|
GliderFlight for Slocum ocean gliders
=====================================
Synopsis
--------
Gliderflight is a python module to calibrate a model that predicts the
glider flight through water. The model results can be used to estimate
the speed through water, a parameter which is required to compute
turbulent dissipation rates from temperature microstructure or shear
probe data, collected with a turbulence profiler mounted on top of an
ocean glider.
Background
------------
The dissipation rate of turbulent kinetic energy is a parameter that
plays a key role in many physical and biogeo chemical processes in
oceans and coastal seas. However, direct oceanic measurements of
turbulence are relatively scarce, as most observations stem from
free-falling profilers, operated from seagoing vessels.
An emerging alternative to ship-based profiling is the use of ocean
gliders with mounted turbulence profilers. A required parameter in
the processing of microstructure shear and temperature measurements is
the speed of flow past the sensors. This speed can be measured
directly with additional sensor, such as an electromagnetic current
meter or mounted acoustic Doppler current profiler, but often gliders
are not equipped with additional velocity sensors. Alternatively, a
glider flight model can be used to estimate the speed through
water. Such a model is described in the paper *A dynamic flight model
for Slocum gliders and implications for turbulence microstructure
measurements* [merckelbach2019]_. This Python
model implements the steady-state and dynamic glider flight models,
described therein.
Documentation
-------------
Documentation of this software package can be found at
https://gliderflight.readthedocs.io/en/latest/
Steady-state model
------------------
The steady-state model implemented, considers a horizontal and
vertical force balance. Vertical forces are a balance between
buoyancy, gravity and the vertical components of the lift and drag
forces. The horizontal force balance consists of the horizontal
components of the lift and drag forces only. These two equations can
be solved for the angle of attack and the speed through water,
determining the flight at any instance of time.
Input to the model comes from parameters measured by the glider, such
as the measured pitch angle (m_pitch), buoyancy change
(m_ballast_pumped or m_de_oil_vol) and the in-situ
density. Furthermore, the model requires the specification of a number
of coefficients:
* mg: mass of the glider (kg)
* Vg: volume of the glider (m³)
* Cd0: parasite drag coefficient
* epsilon: compressibility of the hull (1/Pa)
* ah: lift angle coefficient due to the hull (1/rad)
* Cd1: induced drag coefficient (1/rad²)
Using the depth-rate from the pressure sensor as only model
constraint, the mass (or glider volume) and the parasite drag
coefficient can be determined. To determine the lift angle coefficient
requires an additional constraint that contains a horizontal velocity
component. Details of this procedure are given in [merckelbach2019]_.
Dynamic model
-------------
In addition to a steady-state model, this code also implements a
dynamic model, that is, including the inertial terms. Since this model
needs to be integrated, for which the Runge-Kutta method is used, it
is more computational expensive. The dynamic model produces more
accurate results when forcing conditions change rapidly, such as when
crossing a sharp pycnocline or during the transition from dive to
climb. Apart from the mathematical model underlying, the interfaces to
both models are the same.
Model calibration and data masking
----------------------------------
To calibrate a model, either steady-state or dynamic, we may wish not
to include all the data in the evaluation of the cost-function. To
that end, data can be masked. The Calibrate class provides boolean
operators to do this:
* OR()
* AND()
* NAND()
By default a mask set to False for all data. To mask data for which a
condition evaluates to True, the OR() method should be used. For
example, ::
gm = SteadyStateCalibrate(rho0=1024)
gm.set_input_data(datadict)
condition = depth<10
gm.OR(condition)
which would exclude all data points for which the depth is less than
10 m from the evaluation of the cost-function.
A truth table:
+------+----------+----+-----+----+
| mask | conditon | OR | AND |NAND|
+------+----------+----+-----+----+
| 0 | 0 | 0 | 0 | 1 |
+------+----------+----+-----+----+
| 1 | 0 | 1 | 0 | 1 |
+------+----------+----+-----+----+
| 1 | 1 | 1 | 1 | 0 |
+------+----------+----+-----+----+
| 0 | 1 | 1 | 0 | 1 |
+------+----------+----+-----+----+
Example
-------
An example to calibrate a model::
# create a dictionary with the data
data = dict(time=t, pressure=P, pitch=pitch, buoyancy_change=deltaV)
gm = SteadyStateCalibrate()
# we have to define mass and volume at the minimum
gm.define(mg=70, Vg=70)
gm.set_input_data(data)
# mask all data below 10 m
gm.OR(pressure*10<10)
# mask all data exceeding 60 m
gm.OR(pressure*10>60)
result = gm.calibrate("mg", "Cd0")
print("Calibrated parameters:")
for k,v in result.items():
print("{}: {}".format(k,v)
# Instead of printing the parameters from the results, we could also
# get them from the corresponding attributes: print("Cd0:", gm.Cd0).
print("Cd0:", gm.Cd0)
# We also don't need to run the model again either. The model output
# is also accessible from attributes:
#
# gm.t # time
# gm.U # incident velocity
# gm.alpha # angle of attack
# gm.ug # horizontal speed
# gm.wg # vertical speed
# gm.w # vertical water velocity
# if we want to run a model with a given set of parameters
fm = DynamicGliderModel(dt=1, rho0=1024, k1=0.02, k2=0.92)
# copy the settings from the steady state model
fm.copy_settings(gm)
solution = fm.solve(data)
# solution is now a named tuple, according to the definition:
# Modelresult = namedtuple("Modelresult", "t u w U alpha pitch ww")
How to cite
-----------
When you publish results that were obtained with this software, please use the
following citation:
| Merckelbach, L., A. Berger, G. Krahmann, M. Dengler, and J. Carpenter, 2019: A
| dynamic flight model for Slocum gliders and implications for turbulence
| microstructure measurements. J. Atmos. Oceanic Technol., 36(2),
| 281-296, doi:10.1175/JTECH-D-18-0168.1.
Copyright information
---------------------
Copyright (c) 2018, 2019 Helmholtz Zentrum Geesthacht, Germany
Lucas Merckelbach, lucas.merckelbach@hzg.de
Software is licensed under the MIT licence.
References
----------
.. [merckelbach2019] Merckelbach, L., A. Berger, G. Krahmann, M. Dengler, and J. Carpenter, 2019: A
dynamic flight model for Slocum gliders and implications for
turbulence microstructure measurements. J. Atmos. Oceanic
Technol. 36(2), 281-296, doi:10.1175/JTECH-D-18-0168.1
.. |PyPI version| image:: https://badgen.net/pypi/v/gliderflight
:target: https://pypi.org/project/gliderflight
.. |Docs badge| image:: https://readthedocs.org/projects/dbdreader/badge/?version=latest
:target: https://gliderflight.readthedocs.io/en/latest/
.. |License| image:: https://img.shields.io/badge/License-MIT-blue.svg
:target: https://github.com/smerckel/gliderflight/blob/master/LICENSE
Raw data
{
"_id": null,
"home_page": "https://github.com/smerckel/gliderflight",
"name": "gliderflight",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "ocean gliders,glider flight,oceanography",
"author": "Lucas Merckelbach",
"author_email": "lucas.merckelbach@hzg.de",
"download_url": "https://files.pythonhosted.org/packages/48/a4/aadca74c8e593d6729026f6bd78e87567b74a81b7ceedb0d2078b671120a/gliderflight-1.2.0.tar.gz",
"platform": null,
"description": "|PyPI version| |Docs badge| |License|\n\nGliderFlight for Slocum ocean gliders\n=====================================\n\nSynopsis\n--------\n\nGliderflight is a python module to calibrate a model that predicts the\nglider flight through water. The model results can be used to estimate\nthe speed through water, a parameter which is required to compute\nturbulent dissipation rates from temperature microstructure or shear\nprobe data, collected with a turbulence profiler mounted on top of an\nocean glider.\n\nBackground\n------------\n\nThe dissipation rate of turbulent kinetic energy is a parameter that\nplays a key role in many physical and biogeo chemical processes in\noceans and coastal seas. However, direct oceanic measurements of\nturbulence are relatively scarce, as most observations stem from\nfree-falling profilers, operated from seagoing vessels.\n\n\nAn emerging alternative to ship-based profiling is the use of ocean\ngliders with mounted turbulence profilers. A required parameter in\nthe processing of microstructure shear and temperature measurements is\nthe speed of flow past the sensors. This speed can be measured\ndirectly with additional sensor, such as an electromagnetic current\nmeter or mounted acoustic Doppler current profiler, but often gliders\nare not equipped with additional velocity sensors. Alternatively, a\nglider flight model can be used to estimate the speed through\nwater. Such a model is described in the paper *A dynamic flight model\nfor Slocum gliders and implications for turbulence microstructure\nmeasurements* [merckelbach2019]_. This Python\nmodel implements the steady-state and dynamic glider flight models,\ndescribed therein.\n\nDocumentation\n-------------\n\nDocumentation of this software package can be found at \nhttps://gliderflight.readthedocs.io/en/latest/\n\nSteady-state model\n------------------\n\nThe steady-state model implemented, considers a horizontal and\nvertical force balance. Vertical forces are a balance between\nbuoyancy, gravity and the vertical components of the lift and drag\nforces. The horizontal force balance consists of the horizontal\ncomponents of the lift and drag forces only. These two equations can\nbe solved for the angle of attack and the speed through water,\ndetermining the flight at any instance of time.\n\nInput to the model comes from parameters measured by the glider, such\nas the measured pitch angle (m_pitch), buoyancy change\n(m_ballast_pumped or m_de_oil_vol) and the in-situ\ndensity. Furthermore, the model requires the specification of a number\nof coefficients:\n\n* mg: mass of the glider (kg)\n* Vg: volume of the glider (m\u00b3)\n* Cd0: parasite drag coefficient\n* epsilon: compressibility of the hull (1/Pa)\n* ah: lift angle coefficient due to the hull (1/rad)\n* Cd1: induced drag coefficient (1/rad\u00b2)\n\nUsing the depth-rate from the pressure sensor as only model\nconstraint, the mass (or glider volume) and the parasite drag\ncoefficient can be determined. To determine the lift angle coefficient\nrequires an additional constraint that contains a horizontal velocity\ncomponent. Details of this procedure are given in [merckelbach2019]_.\n\nDynamic model\n-------------\nIn addition to a steady-state model, this code also implements a\ndynamic model, that is, including the inertial terms. Since this model\nneeds to be integrated, for which the Runge-Kutta method is used, it\nis more computational expensive. The dynamic model produces more\naccurate results when forcing conditions change rapidly, such as when\ncrossing a sharp pycnocline or during the transition from dive to\nclimb. Apart from the mathematical model underlying, the interfaces to\nboth models are the same.\n\nModel calibration and data masking\n----------------------------------\n\nTo calibrate a model, either steady-state or dynamic, we may wish not\nto include all the data in the evaluation of the cost-function. To\nthat end, data can be masked. The Calibrate class provides boolean\noperators to do this:\n\n* OR()\n* AND()\n* NAND()\n\nBy default a mask set to False for all data. To mask data for which a\ncondition evaluates to True, the OR() method should be used. For\nexample, ::\n\n gm = SteadyStateCalibrate(rho0=1024)\n gm.set_input_data(datadict)\n \n condition = depth<10\n gm.OR(condition)\n \n\nwhich would exclude all data points for which the depth is less than\n10 m from the evaluation of the cost-function.\n\nA truth table:\n\n+------+----------+----+-----+----+\n| mask | conditon | OR | AND |NAND|\n+------+----------+----+-----+----+\n| 0 | 0 | 0 | 0 | 1 |\n+------+----------+----+-----+----+\n| 1 | 0 | 1 | 0 | 1 |\n+------+----------+----+-----+----+\n| 1 | 1 | 1 | 1 | 0 |\n+------+----------+----+-----+----+\n| 0 | 1 | 1 | 0 | 1 |\n+------+----------+----+-----+----+\n\n\nExample\n-------\n\nAn example to calibrate a model::\n\n # create a dictionary with the data\n\n data = dict(time=t, pressure=P, pitch=pitch, buoyancy_change=deltaV)\n\n gm = SteadyStateCalibrate()\n # we have to define mass and volume at the minimum\n gm.define(mg=70, Vg=70)\n\n gm.set_input_data(data)\n\n # mask all data below 10 m\n gm.OR(pressure*10<10)\n # mask all data exceeding 60 m\n gm.OR(pressure*10>60)\n\n result = gm.calibrate(\"mg\", \"Cd0\")\n \n print(\"Calibrated parameters:\")\n for k,v in result.items():\n print(\"{}: {}\".format(k,v)\n\n # Instead of printing the parameters from the results, we could also\n # get them from the corresponding attributes: print(\"Cd0:\", gm.Cd0).\n\n print(\"Cd0:\", gm.Cd0)\n\n # We also don't need to run the model again either. The model output\n # is also accessible from attributes:\n #\n # gm.t # time\n # gm.U # incident velocity\n # gm.alpha # angle of attack\n # gm.ug # horizontal speed\n # gm.wg # vertical speed\n # gm.w # vertical water velocity\n \n # if we want to run a model with a given set of parameters\n\n fm = DynamicGliderModel(dt=1, rho0=1024, k1=0.02, k2=0.92)\n # copy the settings from the steady state model\n fm.copy_settings(gm)\n\n solution = fm.solve(data)\n \n # solution is now a named tuple, according to the definition:\n # Modelresult = namedtuple(\"Modelresult\", \"t u w U alpha pitch ww\")\n\n\nHow to cite\n-----------\nWhen you publish results that were obtained with this software, please use the\nfollowing citation:\n\n| Merckelbach, L., A. Berger, G. Krahmann, M. Dengler, and J. Carpenter, 2019: A\n| dynamic flight model for Slocum gliders and implications for turbulence\n| microstructure measurements. J. Atmos. Oceanic Technol., 36(2),\n| 281-296, doi:10.1175/JTECH-D-18-0168.1.\n\n\nCopyright information\n---------------------\nCopyright (c) 2018, 2019 Helmholtz Zentrum Geesthacht, Germany\n Lucas Merckelbach, lucas.merckelbach@hzg.de\n\nSoftware is licensed under the MIT licence.\n\nReferences\n----------\n.. [merckelbach2019] Merckelbach, L., A. Berger, G. Krahmann, M. Dengler, and J. Carpenter, 2019: A\n dynamic flight model for Slocum gliders and implications for\n turbulence microstructure measurements. J. Atmos. Oceanic\n Technol. 36(2), 281-296, doi:10.1175/JTECH-D-18-0168.1\n\n.. |PyPI version| image:: https://badgen.net/pypi/v/gliderflight\n :target: https://pypi.org/project/gliderflight\n.. |Docs badge| image:: https://readthedocs.org/projects/dbdreader/badge/?version=latest\n :target: https://gliderflight.readthedocs.io/en/latest/\n.. |License| image:: https://img.shields.io/badge/License-MIT-blue.svg\n :target: https://github.com/smerckel/gliderflight/blob/master/LICENSE \n\n \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Flight model for Slocum ocean gliders",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/smerckel/gliderflight"
},
"split_keywords": [
"ocean gliders",
"glider flight",
"oceanography"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "48a4aadca74c8e593d6729026f6bd78e87567b74a81b7ceedb0d2078b671120a",
"md5": "33d3e1fbeeb27232c8b54ac7643bb3a4",
"sha256": "8a19ba3f8396cde4f40d018d12e94eccfe79f1a25dd0af505948bd06cce28377"
},
"downloads": -1,
"filename": "gliderflight-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "33d3e1fbeeb27232c8b54ac7643bb3a4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 363988,
"upload_time": "2023-05-09T09:25:55",
"upload_time_iso_8601": "2023-05-09T09:25:55.162744Z",
"url": "https://files.pythonhosted.org/packages/48/a4/aadca74c8e593d6729026f6bd78e87567b74a81b7ceedb0d2078b671120a/gliderflight-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-09 09:25:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "smerckel",
"github_project": "gliderflight",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "gliderflight"
}
JSON
