Loading Conditions#

Classes for managing mass inventories and tank fill overrides to define operational profiles.

MassCategory#

class MassCategory#

Category of a mass item.

static lightship()#

Creates a Lightship category.

static deadweight()#

Creates a Deadweight category.

static other()#

Creates an Other category (default).

MassItem#

class MassItem(name, mass, cog, category=None)#

A single mass item with name, mass, position, and optional category.

Parameters:

  • name – Identifier for the mass item.

  • mass – Mass in kg.

  • cog – Center of gravity (lcg, tcg, vcg) in meters.

  • category – Optional MassCategory (default: Other).

__init__(name, mass, cog, category=None)#

Creates a MassItem.

Properties

name: str
mass: float#
cog: tuple[float, float, float]#
category: MassCategory#

LoadingCondition#

class LoadingCondition(name)#

A complete loading condition with mass items and tank fill overrides.

Parameters:

name – Name of the loading condition.

__init__(name)#

Creates a LoadingCondition.

Properties

name: str

Name of the loading condition.

Mass Management

add_mass(item)#

Add a MassItem.

Parameters:

item – A MassItem instance.

add_mass_simple(name, mass, cog, category=None)#

Add a mass item by parameters (convenience).

Parameters:

  • name – Identifier for the mass item.

  • mass – Mass in kg.

  • cog – Center of gravity (lcg, tcg, vcg) in meters.

  • category – Optional MassCategory (default: Other).

remove_mass(name)#

Remove a mass item by name.

Parameters:

name – Name of the mass.

Returns:

True if found and removed.

Return type:

bool

get_masses()#

Returns all mass items.

Return type:

list[MassItem]

num_masses()#

Returns the number of mass items.

Return type:

int

Tank Fill Overrides

set_tank_fill(tank_name, fill_level)#

Set a tank fill override by fill level (0.0 to 1.0).

set_tank_fill_percent(tank_name, fill_percent)#

Set a tank fill override by percentage (0 to 100).

remove_tank_fill(tank_name)#

Remove a tank fill override.

Returns:

True if found and removed.

Return type:

bool

num_tank_overrides()#

Returns the number of tank fill overrides.

Return type:

int

get_tank_fills()#

Returns tank fill overrides as a dictionary.

Returns:

{name: fill_level}

Return type:

dict[str, float]

Application & Calculation

apply(vessel)#

Apply tank fill overrides to the vessel’s tanks. Only tanks listed in overrides are modified. Other tanks keep their current fill level.

Parameters:

vessel – Vessel instance.

total_displacement(vessel)#

Returns the total displacement (masses + tank fluid masses) in kg. Must be called after apply().

Parameters:

vessel – Vessel instance.

Return type:

float

total_cog(vessel)#

Returns the combined center of gravity in meters. Must be called after apply().

Parameters:

vessel – Vessel instance.

Returns:

(lcg, tcg, vcg)

Return type:

tuple[float, float, float]

resolve(vessel)#

Returns (total_displacement, (lcg, tcg, vcg)) in a single call. Must be called after apply().

Parameters:

vessel – Vessel instance.

Return type:

tuple[float, tuple[float, float, float]]

item_displacement()#

Returns the displacement of mass items only (excluding tank fluids) in kg.

Return type:

float

item_cog()#

Returns the center of gravity of mass items only (lcg, tcg, vcg) in meters.

Return type:

tuple[float, float, float]

resolve_items()#

Returns (item_displacement, (lcg, tcg, vcg)) in a single call. Use this for stability calculations to avoid double-counting tank masses.

Note

It is highly recommended to use the convenience methods directly on the calculators: gz_curve_from_loading() and from_loading(). These methods automatically handle the save/restore process for tank configurations.

Return type:

tuple[float, tuple[float, float, float]]

Serialization and Copying

to_json()#

Serialize to JSON string.

Return type:

str

static from_json(json_str)#

Deserialize from JSON string.

Return type:

LoadingCondition

save_json(path)#

Save to JSON file.

static load_json(path)#

Load from JSON file.

static from_csv(csv_str)#

Deserialize from CSV string. A unified CSV format is used to handle both Mass Items and Tank Fill Overrides.

CSV Format Example:

Type,Name,Mass,LCG,TCG,VCG,Category,FillPercent
Mass,Lightship,5000000.0,45.0,0.0,4.5,Lightship,
Mass,Crew,3000.0,35.0,0.0,8.0,Other,
Tank,FO_1P,,,,,,95.0
Tank,FW_1,,,,,,50.0

You can download this template here: loading_condition_template.csv

Return type:

LoadingCondition

static load_csv(path)#

Load from CSV file. Uses the same unified format as from_csv.

Return type:

LoadingCondition

copy(name=None)#

Create a copy, optionally with a new name.

Parameters:

name – New name

Return type:

LoadingCondition