shipmmg package

Submodules

shipmmg.draw_obj module

draw_obj.

Base class for drawing object not only for shipmmg.

class shipmmg.draw_obj.DrawObj(ax)[source]

Bases: object

DrawObj class.

General class for drawing object by using matplotlib.animation. Multiple ships can be drawn by using this class.

draw_obj_with_angle(center_x_list, center_y_list, shape_list, angle_list, obj='ship')[source]

Draw square image with angle.

Parameters

center_x_list (List[float]) – list of the center x position of the square
center_y_list (List[float]) – list of the center y position of the square
shape_list (List[float]) – list of the square’s shape(length/2, width/2)
angle_list (List[float]) – list of in radians
(str (obj) – optional): object type, ‘ship’ or ‘square’

Returns

List of Image

Return type

Image

shipmmg.kt module

kt.

KT (1DOF) simulation code

\(T dr = -r + K \delta\)

class shipmmg.kt.KTParams(K: float, T: float)[source]

Bases: object

Dataclass for setting KT parameters of KT simulation.

K

One of parameters in KT model. [1/s]

Type: float

T

One of parameters in KT model. [s]

Type: float

K: float

T: float

shipmmg.kt.simulate(K: float, T: float, time_list: List[float], δ_list: List[float], r0: float = 0.0, method: str = 'RK45', t_eval=None, events=None, vectorized=False, **options)[source]

KT simulation.

KT simulation by following equation of motion.

\(T dr = -r + K \delta\)

Parameters

K (float) – parameter K of KT model.
T (float) – parameter T of KT model.
time_list (list[float]) – time list of simulation.
δ_list (list[float]) – rudder angle list of simulation.
r0 (float, optional) – rate of turn [rad/s] in initial condition (time_list[0]). Defaults to 0.0.
method (str, optional) –
Integration method to use in scipy.integrate.solve_ivp():

”RK45” (default):
Explicit Runge-Kutta method of order 5(4). The error is controlled assuming accuracy of the fourth-order method, but steps are taken using the fifth-order accurate formula (local extrapolation is done). A quartic interpolation polynomial is used for the dense output. Can be applied in the complex domain.

”RK23”:
Explicit Runge-Kutta method of order 3(2). The error is controlled assuming accuracy of the second-order method, but steps are taken using the third-order accurate formula (local extrapolation is done). A cubic Hermite polynomial is used for the dense output. Can be applied in the complex domain.

”DOP853”:
Explicit Runge-Kutta method of order 8. Python implementation of the “DOP853” algorithm originally written in Fortran. A 7-th order interpolation polynomial accurate to 7-th order is used for the dense output. Can be applied in the complex domain.

”Radau”:
Implicit Runge-Kutta method of the Radau IIA family of order 5. The error is controlled with a third-order accurate embedded formula. A cubic polynomial which satisfies the collocation conditions is used for the dense output.

”BDF”:
Implicit multi-step variable-order (1 to 5) method based on a backward differentiation formula for the derivative approximation. A quasi-constant step scheme is used and accuracy is enhanced using the NDF modification. Can be applied in the complex domain.

”LSODA”:
Adams/BDF method with automatic stiffness detection and switching. This is a wrapper of the Fortran solver from ODEPACK.
t_eval (array_like or None, optional) – Times at which to store the computed solution, must be sorted and lie within t_span. If None (default), use points selected by the solver.
events (callable, or list of callables, optional) –
Events to track. If None (default), no events will be tracked. Each event occurs at the zeros of a continuous function of time and state. Each function must have the signature event(t, y) and return a float. The solver will find an accurate value of t at which event(t, y(t)) = 0 using a root-finding algorithm. By default, all zeros will be found. The solver looks for a sign change over each step, so if multiple zero crossings occur within one step, events may be missed. Additionally each event function might have the following attributes:

terminal (bool, optional):
Whether to terminate integration if this event occurs. Implicitly False if not assigned.

direction (float, optional):
Direction of a zero crossing. If direction is positive, event will only trigger when going from negative to positive, and vice versa if direction is negative. If 0, then either direction will trigger event. Implicitly 0 if not assigned.

You can assign attributes like event.terminal = True to any function in Python.
vectorized (bool, optional) – Whether fun is implemented in a vectorized fashion. Default is False.
options –
Options passed to a chosen solver. All options available for already implemented solvers are listed in scipy.integrate.solve_ivp():

Returns

t (ndarray, shape (n_points,)):

Time points.

y (ndarray, shape (n_points,)):

Values of the solution at t.

sol (OdeSolution):

Found solution as OdeSolution instance from KT simulation.

t_events (list of ndarray or None):

Contains for each event type a list of arrays at which an event of that type event was detected. None if events was None.

y_events (list of ndarray or None):

For each value of t_events, the corresponding value of the solution. None if events was None.

nfev (int):

Number of evaluations of the right-hand side.

njev (int):

Number of evaluations of the jacobian.

nlu (int):

Number of LU decomposition.

status (int):

Reason for algorithm termination:

-1: Integration step failed.
0: The solver successfully reached the end of tspan.
1: A termination event occurred.

message (string):

Human-readable description of the termination reason.

success (bool):

True if the solver reached the interval end or a termination event occurred (status >= 0).

Return type

Bunch object with the following fields defined

Examples

>>> K = 0.15
>>> T = 60.0
>>> duration = 300
>>> num_of_sampling = 3000
>>> time_list = np.linspace(0.00, duration, num_of_sampling)
>>> δ_list = 35 * np.pi / 180 * np.sin(3.0 * np.pi / Ts * time_list)
>>> r0 = 0.0
>>> sol = simulate_kt(K, T, time_list, δ_list, r0)
>>> result = sol.sol(time_list)

shipmmg.kt.simulate_kt(kt_params: shipmmg.kt.KTParams, time_list: List[float], δ_list: List[float], r0: float = 0.0, method: str = 'RK45', t_eval=None, events=None, vectorized=False, **options)[source]

KT simulation.

KT simulation by following equation of motion.

\(T dr = -r + K \delta\)

Parameters

kt_params (KTParams) – KT parameters.
time_list (list[float]) – time list of simulation.
δ_list (list[float]) – rudder angle list of simulation.
r0 (float, optional) – rate of turn [rad/s] in initial condition (time_list[0]). Defaults to 0.0.
method (str, optional) –
Integration method to use in scipy.integrate.solve_ivp():

”RK45” (default):
Explicit Runge-Kutta method of order 5(4). The error is controlled assuming accuracy of the fourth-order method, but steps are taken using the fifth-order accurate formula (local extrapolation is done). A quartic interpolation polynomial is used for the dense output. Can be applied in the complex domain.

”RK23”:
Explicit Runge-Kutta method of order 3(2). The error is controlled assuming accuracy of the second-order method, but steps are taken using the third-order accurate formula (local extrapolation is done). A cubic Hermite polynomial is used for the dense output. Can be applied in the complex domain.

”DOP853”:
Explicit Runge-Kutta method of order 8. Python implementation of the “DOP853” algorithm originally written in Fortran. A 7-th order interpolation polynomial accurate to 7-th order is used for the dense output. Can be applied in the complex domain.

”Radau”:
Implicit Runge-Kutta method of the Radau IIA family of order 5. The error is controlled with a third-order accurate embedded formula. A cubic polynomial which satisfies the collocation conditions is used for the dense output.

”BDF”:
Implicit multi-step variable-order (1 to 5) method based on a backward differentiation formula for the derivative approximation. A quasi-constant step scheme is used and accuracy is enhanced using the NDF modification. Can be applied in the complex domain.

”LSODA”:
Adams/BDF method with automatic stiffness detection and switching. This is a wrapper of the Fortran solver from ODEPACK.
t_eval (array_like or None, optional) – Times at which to store the computed solution, must be sorted and lie within t_span. If None (default), use points selected by the solver.
events (callable, or list of callables, optional) –
Events to track. If None (default), no events will be tracked. Each event occurs at the zeros of a continuous function of time and state. Each function must have the signature event(t, y) and return a float. The solver will find an accurate value of t at which event(t, y(t)) = 0 using a root-finding algorithm. By default, all zeros will be found. The solver looks for a sign change over each step, so if multiple zero crossings occur within one step, events may be missed. Additionally each event function might have the following attributes:

terminal (bool, optional):
Whether to terminate integration if this event occurs. Implicitly False if not assigned.

direction (float, optional):
Direction of a zero crossing. If direction is positive, event will only trigger when going from negative to positive, and vice versa if direction is negative. If 0, then either direction will trigger event. Implicitly 0 if not assigned.

You can assign attributes like event.terminal = True to any function in Python.
vectorized (bool, optional) – Whether fun is implemented in a vectorized fashion. Default is False.
options –
Options passed to a chosen solver. All options available for already implemented solvers are listed in scipy.integrate.solve_ivp():

Returns

t (ndarray, shape (n_points,)):

Time points.

y (ndarray, shape (n_points,)):

Values of the solution at t.

sol (OdeSolution):

Found solution as OdeSolution instance from KT simulation.

t_events (list of ndarray or None):

Contains for each event type a list of arrays at which an event of that type event was detected. None if events was None.

y_events (list of ndarray or None):

For each value of t_events, the corresponding value of the solution. None if events was None.

nfev (int):

Number of evaluations of the right-hand side.

njev (int):

Number of evaluations of the jacobian.

nlu (int):

Number of LU decomposition.

status (int):

Reason for algorithm termination:

-1: Integration step failed.
0: The solver successfully reached the end of tspan.
1: A termination event occurred.

message (string):

Human-readable description of the termination reason.

success (bool):

True if the solver reached the interval end or a termination event occurred (status >= 0).

Return type

Bunch object with the following fields defined

Examples

>>> kt_params = KTParams(K=0.15, T=60.0)
>>> duration = 300
>>> num_of_sampling = 3000
>>> time_list = np.linspace(0.00, duration, num_of_sampling)
>>> δ_list = 35 * np.pi / 180 * np.sin(3.0 * np.pi / Ts * time_list)
>>> r0 = 0.0
>>> sol = simulate_kt(kt_params, time_list, δ_list, r0)
>>> result = sol.sol(time_list)

shipmmg.kt.zigzag_test_kt(kt_params: shipmmg.kt.KTParams, target_δ_rad: float, target_ψ_rad_deviation: float, time_list: List[float], δ0: float = 0.0, δ_rad_rate: float = 0.017453292519943295, r0: float = 0.0, ψ0: float = 0.0, method: str = 'RK45', t_eval=None, events=None, vectorized=False, **options)[source]

Zig-zag test simulation.

Parameters

kt_params (KTParams) – KT parameters.
target_δ_rad (float) – target absolute value of rudder angle.
target_ψ_rad_deviation (float) – target absolute value of psi deviation from ψ0[rad].
time_list (list[float]) – time list of simulation.
δ0 (float) – Initial rudder angle [rad]. Defaults to 0.0.
δ_rad_rate (float) – Initial rudder angle rate [rad/s]. Defaults to 1.0.
r0 (float, optional) – rate of turn [rad/s] in initial condition (time_list[0]). Defaults to 0.0.
ψ0 (float, optional) – Inital azimuth [rad] in initial condition (time_list[0]).. Defaults to 0.0.
method (str, optional) –
Integration method to use in scipy.integrate.solve_ivp():

”RK45” (default):
Explicit Runge-Kutta method of order 5(4). The error is controlled assuming accuracy of the fourth-order method, but steps are taken using the fifth-order accurate formula (local extrapolation is done). A quartic interpolation polynomial is used for the dense output. Can be applied in the complex domain.

”RK23”:
Explicit Runge-Kutta method of order 3(2). The error is controlled assuming accuracy of the second-order method, but steps are taken using the third-order accurate formula (local extrapolation is done). A cubic Hermite polynomial is used for the dense output. Can be applied in the complex domain.

”DOP853”:
Explicit Runge-Kutta method of order 8. Python implementation of the “DOP853” algorithm originally written in Fortran. A 7-th order interpolation polynomial accurate to 7-th order is used for the dense output. Can be applied in the complex domain.

”Radau”:
Implicit Runge-Kutta method of the Radau IIA family of order 5. The error is controlled with a third-order accurate embedded formula. A cubic polynomial which satisfies the collocation conditions is used for the dense output.

”BDF”:
Implicit multi-step variable-order (1 to 5) method based on a backward differentiation formula for the derivative approximation. A quasi-constant step scheme is used and accuracy is enhanced using the NDF modification. Can be applied in the complex domain.

”LSODA”:
Adams/BDF method with automatic stiffness detection and switching. This is a wrapper of the Fortran solver from ODEPACK.
t_eval (array_like or None, optional) – Times at which to store the computed solution, must be sorted and lie within t_span. If None (default), use points selected by the solver.
events (callable, or list of callables, optional) –
Events to track. If None (default), no events will be tracked. Each event occurs at the zeros of a continuous function of time and state. Each function must have the signature event(t, y) and return a float. The solver will find an accurate value of t at which event(t, y(t)) = 0 using a root-finding algorithm. By default, all zeros will be found. The solver looks for a sign change over each step, so if multiple zero crossings occur within one step, events may be missed. Additionally each event function might have the following attributes:

terminal (bool, optional):
Whether to terminate integration if this event occurs. Implicitly False if not assigned.

direction (float, optional):
Direction of a zero crossing. If direction is positive, event will only trigger when going from negative to positive, and vice versa if direction is negative. If 0, then either direction will trigger event. Implicitly 0 if not assigned.

You can assign attributes like event.terminal = True to any function in Python.
vectorized (bool, optional) – Whether fun is implemented in a vectorized fashion. Default is False.
options –
Options passed to a chosen solver. All options available for already implemented solvers are listed in scipy.integrate.solve_ivp():

Returns

list of rudder angle. final_r_list (list[float])) : list of rate of turn.

Return type

final_δ_list (list[float]))

shipmmg.mmg_3dof module

mmg_3dof.

MMG (3DOF) simulation code

\[ \begin{align}\begin{aligned}m (\dot{u}-vr)&=-m_x\dot{u}+m_yvr+X_H+X_P+X_R\\m (\dot{v}+ur)&=-m_y\dot{v}+m_xur+Y_H+Y_R\\I_{zG}\dot{r}&=-J_Z\dot{r}+N_H+N_R\end{aligned}\end{align} \]

class shipmmg.mmg_3dof.Mmg3DofBasicParams(L_pp: float, B: float, d: float, x_G: float, D_p: float, m: float, I_zG: float, A_R: float, η: float, m_x: float, m_y: float, J_z: float, f_α: float, ε: float, t_R: float, x_R: float, a_H: float, x_H: float, γ_R_minus: float, γ_R_plus: float, l_R: float, κ: float, t_P: float, w_P0: float, x_P: float)[source]

Bases: object

Dataclass for setting basic parameters of MMG 3DOF.

L_pp

Ship length between perpendiculars [m]

Type: float

B

Ship breadth [m]

Type: float

d

Ship draft [m]

Type: float

x_G

Longitudinal coordinate of center of gravity of ship [m]

Type: float

D_p

Propeller diameter [m]

Type: float

m

Ship mass [kg]

Type: float

I_zG

Moment of inertia of ship around center of gravity

Type: float

A_R

Profile area of movable part of mariner rudder [m^2]

Type: float

η

Ratio of propeller diameter to rudder span (=D_p/HR)

Type: float

m_x

Added masses of x axis direction [kg]

Type: float

m_y

Added masses of y axis direction [kg]

Type: float

J_z

Added moment of inertia

Type: float

f_α

Rudder lift gradient coefficient

Type: float

ϵ

Ratio of wake fraction at propeller and rudder positions

Type: float

t_R

Steering resistance deduction factor

Type: float

x_R

Longitudinal coordinate of rudder position.

Type: float

a_H

Rudder force increase factor

Type: float

x_H

Longitudinal coordinate of acting point of the additional lateral force component induced by steering

Type: float

γ_R_minus

Flow straightening coefficient if βR < 0

Type: float

γ_R_plus

Flow straightening coefficient if βR > 0

Type: float

l_R

Effective longitudinal coordinate of rudder position in formula of βR

Type: float

κ

An experimental constant for expressing uR

Type: float

t_P

Thrust deduction factor

Type: float

w_P0

Wake coefficient at propeller position in straight moving

Type: float

x_P

Effective Longitudinal coordinate of propeller position in formula of βP

Type: float

Note

For more information, please see the following articles.

Yasukawa, H., Yoshimura, Y. (2015) Introduction of MMG standard method for ship maneuvering predictions. J Mar Sci Technol 20, 37-52 https://doi.org/10.1007/s00773-014-0293-y

A_R: float

B: float

D_p: float

I_zG: float

J_z: float

L_pp: float

a_H: float

d: float

f_α: float

l_R: float

m: float

m_x: float

m_y: float

t_P: float

t_R: float

w_P0: float

x_G: float

x_H: float

x_P: float

x_R: float

γ_R_minus: float

γ_R_plus: float

ε: float

η: float

κ: float

class shipmmg.mmg_3dof.Mmg3DofManeuveringParams(k_0: float, k_1: float, k_2: float, R_0_dash: float, X_vv_dash: float, X_vr_dash: float, X_rr_dash: float, X_vvvv_dash: float, Y_v_dash: float, Y_r_dash: float, Y_vvv_dash: float, Y_vvr_dash: float, Y_vrr_dash: float, Y_rrr_dash: float, N_v_dash: float, N_r_dash: float, N_vvv_dash: float, N_vvr_dash: float, N_vrr_dash: float, N_rrr_dash: float)[source]

Bases: object

Dataclass for setting maneuvering parameters of MMG 3ODF.

k_0

One of manuevering parameters of coefficients representing K_T

Type: float

k_1

One of manuevering parameters of coefficients representing K_T

Type: float

k_2

One of manuevering parameters of coefficients representing K_T

Type: float

R_0_dash

One of manuevering parameters of Ship resistance coefficient in straight moving

Type: float

X_vv_dash