hrosailing

![Still in development. In particular we do not guarantee backwards compatibility to the versions 0.x.x.]!

The hrosailing package provides various tools and interfaces to visualize, create and work with polar (performance) diagrams.

The main interface being the PolarDiagram interface for the creation of custom polar diagrams, which is compatible with the functionalities of this package. hrosailing also provides some pre-implemented classes inheriting from PolarDiagram which can be used as well.

The package contains a data processing framework, centered around the PolarPipeline class, to generate polar diagrams from raw data.

pipelinecomponents provides many out of the box parts for the aforementioned framework as well as the possibility to easily create own ones.

The package also provides many navigational usages of polar (performance) diagrams with cruising.

You can find the documentation here. See also the examples below for some showcases.

Installation

The recommended way to install hrosailing is with pip:

pip install hrosailing

It has the following dependencies:

• numpy version 1.22.0
• scipy version 1.9.1
• matplotlib version 3.4.3

For some features it might be necessary to also use:

• pynmea2 version 1.18.0
• pandas version 1.3.3
• netCDF4 version 1.6.1
• meteostat version 1.6.5

The hrosailing package might also be compatible (in large) with other versions of Python, together with others versions of some of the used packages. However, this has not been tested properly.

Examples

In the following we showcase some of the capabilities of hrosailing. All definitions of an example code might be used in the succeeding examples.

Serialization of PolarDiagram objects

For a first example, lets say we obtained some table with polar performance diagram data, like the one available here, and call the file testdata.csv.

```python import hrosailing.polardiagram as pol

the format of testdata.csv is a tab separated one

supported by the keyword array

pd = pol.from_csv("testdata.csv", fmt="array")

for symmetric results

pd = pd.symmetrize()

serializes the polar diagram to a .csv file

in the style of an intern format

pd.tocsv("polardiagram.csv")

the default format is the intern format hro

pd2 = pol.fromcsv("polardiagram.csv") ```

Currently serialization is only supported for some csv-formats, see also csv-format-examples for example files for the currently supported formats. See also Issue #1 for a plan to add more serialization options.

Visualizing polar diagrams

```python import matplotlib.pyplot as plt import hrosailing.plotting as plot

ws = [10, 20, 30]

plt.subplot(2, 2, 1, projection="hro polar").plot(pd, ws=ws) plt.subplot(2, 2, 2, projection="hro polar").plot(pd, ws=ws, useconvexhull=True) plt.subplot(2, 2, 3, projection="hro flat").plot(pd, ws=ws) plt.subplot(2, 2, 4, projection="hro color gradient").plot(pd)

plt.show() ```

3d visualization is also supported. python plot.plot_3d(pd) plt.show()

Iterate over polar diagram data

We can also directly iterate and/or evaluate the wind angles, wind speeds and boat speeds of the polar diagram.

```python import numpy as np

def randomshiftedpt(pt, mul): pt = np.array(pt) rand = np.random.random(pt.shape) - 0.5 rand *= np.array(mul) randompt = pt + rand for i in range(3): randompt[i] = max(randompt[i], 0) return randompt

data = np.array([ randomshiftedpt([ws, wa, pd(ws, wa)], [10, 5, 2]) for wa in pd.windangles for ws in pd.windspeeds for _ in range(6) ]) data = data[np.random.choice(len(data), size=500)] ```

Creating polar diagrams from raw data

```python import hrosailing.pipeline as pipe import hrosailing.processing as proc

polpips = [ pipe.PolarPipeline( datahandler=proc.ArrayHandler(), imputator=proc.RemoveOnlyImputator(), extension=pipe.TableExtension() ), pipe.PolarPipeline( datahandler=proc.ArrayHandler(), imputator=proc.RemoveOnlyImputator(), extension=pipe.PointcloudExtension() ), pipe.PolarPipeline( datahandler=proc.ArrayHandler(), imputator=proc.RemoveOnlyImputator(), extension=pipe.CurveExtension() ) ]

here data is treated as some obtained measurements given as

a numpy.ndarray

pds = [ polpip( [(data, ["Wind speed", "Wind angle", "Boat speed"])] ).polardiagram for polpip in pol_pips ]

for i, pd in enumerate(pds): plt.subplot(1, 3, i+1, projection="hro polar").plot(pd, ws=ws)

plt.tight_layout() plt.show() ```

If we are unhappy with the default behaviour of the pipelines, we can customize one or more components of it.

Customizing PolarPipeline

```python import hrosailing.models as models

class MyInfluenceModel(models.InfluenceModel): def remove_influence(self, data): tws = np.array(data["TWS"]) twa = np.array(data["TWA"]) bsp = np.array(data["BSP"]) return np.array([ tws, (twa + 90)%360, bsp**2 ]).transpose()

def add_influence(self, pd, influence_data: dict):
    pass

class MyFilter(proc.Filter): def filter(self, wts): return np.logical_or(wts <= 0.2, wts >= 0.8)

def mymodelfunc(ws, wa, params): return params[0] + params[1]wa + params[2]ws + params[3]ws*wa

myregressor = proc.LeastSquareRegressor( modelfunc=mymodelfunc, init_vals=(1, 2, 3, 4) )

myextension = pipe.CurveExtension( regressor=myregressor )

def my_norm(pt): return np.linalg.norm(pt, axis=1)**4

mypolpip = pipe.PolarPipeline( datahandler=proc.ArrayHandler(), imputator=proc.RemoveOnlyImputator(), influencemodel=MyInfluenceModel(), postweigher=proc.CylindricMeanWeigher(radius=2, norm=mynorm), extension=myextension, postfilter=MyFilter() )

out = mypolpip([(data, ["Wind speed", "Wind angle", "Boat speed"])]) my_pd = out.polardiagram ```

The customizations above are arbitrary and lead to comparably bad results:

python plot.plot_polar(my_pd, ws=ws) plt.show()

Including Influences and Weather models

For the next example we initialize a simple influence model and a random weather model.

```python from datetime import timedelta from datetime import datetime as dt

class MyInfluenceModel(models.InfluenceModel):

def remove_influence(self, data):
    pass

def add_influence(self, pd, data, **kwargs):
    ws, wa, wave_height = np.array(
        [data["TWS"], data["TWA"], data["WVHGT"]]
    )
    twa = (wa + 5)%360
    tws = ws + ws/wave_height
    return [pd(ws, wa) for ws, wa in zip(tws, twa)]

im = MyInfluenceModel()

n, m, k, l = 500, 50, 40, 3

data = 20 * (np.random.random((n, m, k, l)))

wm = models.GriddedWeatherModel( data=data, times=[dt.now() + i * timedelta(hours=1) for i in range(n)], lats=np.linspace(40, 50, m), lons=np.linspace(40, 50, k), attrs=["TWS", "TWA", "WVHGT"] ) ```

Computing Isochrones

```python import hrosailing.cruising as cruise

start = (42.5, 43.5)

isochrones = [ cruise.isochrone( pd=pd, start=start, starttime=dt.now(), direction=direction, wm=wm, im=im, totaltime=1 / 3 ) for direction in range(0, 360, 5) ]

coordinates, _ = zip(isochrones) lats, longs = zip(coordinates)

for lat, long in coordinates: plt.plot([start[0], lat], [start[1], long], color="lightgray") plt.plot(lats, longs, ls="", marker=".")

plt.show() ```

License

The hrosailing package is published under the Apache 2.0 License, see also License

Citing

Also see Citation.

TODO

Todo