ModelingToolkit Standard Library: Hydraulic Components

HydraulicPort(; name)

Connector port for hydraulic components.

States:

• p: [Pa] gauge total pressure
• dm: [kg/s] mass flow

HydraulicFluid(; density = 997, bulk_modulus = 2.09e9, viscosity = 0.0010016, gas_density = 0.0073955, gas_pressure = -1000, n = 1, let_gas = 1, name)

Fluid parameter setter for isothermal compressible fluid domain. Defaults given for water at 20°C and 0Pa gage (1atm absolute) reference pressure. Density is modeled using the Tait equation of state. For pressures below the reference pressure, density is linearly interpolated to the gas state (when let_gas is set to 1), this helps prevent pressures from going below the reference pressure.

Parameters:

• ρ: [kg/m^3] fluid density at 0Pa reference gage pressure (set by density argument)
• Β: [Pa] fluid bulk modulus describing the compressibility (set by bulk_modulus argument)
• μ: [Pa*s] or [kg/m-s] fluid dynamic viscosity (set by viscosity argument)
• n: density exponent
• let_gas: set to 1 to allow fluid to transition from liquid to gas (for density calculation only)
• ρ_gas: [kg/m^3] density of fluid in gas state at reference gage pressure p_gas (set by gas_density argument)
• p_gas: [Pa] reference pressure (set by gas_pressure argument)

friction_factor(dm, area, d_h, viscosity, shape_factor)

Calculates the friction factor $f$ for fully developed flow in a tube such that $Δp = f \cdot \rho \frac{u^2}{2} \frac{l}{d_h}$ where

• $Δp$: [Pa] is the pressure difference over the tube length $l$
• $\rho$: [kg/m^3] is the average fluid density
• $u$: [m/s] is the average fluid velocity
• $l$: [m] is the tube length

The friction factor is calculated for laminar and turbulent flow with a transition region between Reynolds number 2000 to 3000. Turbulent flow equation is for smooth tubes, valid for the Reynolds number range up to 5e6.

Arguments:

• dm: [kg/s] mass flow
• area: [m^2] tube cross sectional area
• d_h: [m] tube hydraulic diameter. For circular tubes d_h is the tube diameter, otherwise it can be found from 4*area/perimeter
• density: [kg/m^3] fluid density
• viscosity: [Pa*s] or [kg/m-s] fluid dynamic viscosity
• shape_factor: the constant defining the laminar fully developed constant f*Re related to the shape of the tube cross section

Reference: Introduction to Fluid Mechanics, Fox & McDonald, 5th Edition, equations 8.19 and 8.21

Cap(; name)

Caps a hydraulic port to prevent mass flow in or out.

Connectors:

• port: hydraulic port

Open(; name)

Provides an "open" boundary condition for a hydraulic port such that mass flow dm is non-zero. This is opposite from an un-connected hydraulic port or the Cap boundary component which sets the mass flow dm to zero.

Connectors:

• port: hydraulic port

TubeBase(add_inertia = true, variable_length = true; area, length_int, head_factor = 1, perimeter = 2 * sqrt(area * pi), shape_factor = 64, name)

Variable length internal flow model of the fully developed incompressible flow friction. Includes optional inertia term when add_inertia = true to model wave propagation. Hydraulic ports have equal flow but variable pressure. Density is averaged over the pressures, used to calculated average flow velocity and flow friction.

States:

• x: [m] length of the pipe
• ddm: [kg/s^2] Rate of change of mass flow rate in control volume.

Parameters:

• area: [m^2] tube cross sectional area
• length_int: [m] initial tube length
• perimeter: [m] perimeter of the pipe cross section (needed only for non-circular pipes)
• shape_factor: shape factor, see friction_factor function
• head_factor: effective length multiplier, used to account for addition friction from flow development and additional friction such as pipe bends, entrance/exit lossses, etc.

Connectors:

• port_a: hydraulic port
• port_b: hydraulic port

Tube(N, add_inertia=true; p_int, area, length, head_factor=1, perimeter = 2 * sqrt(area * pi), shape_factor = 64, name)

Constant length internal flow model discretized by N (FixedVolume: N, TubeBase:N-1) which models the fully developed flow friction, compressibility (when N>1), and inertia effects when add_inertia = true. See TubeBase and FixedVolume for more information.

Parameters:

• p_int: [Pa] initial pressure
• area: [m^2] tube cross sectional area
• length: [m] real length of the tube
• perimeter: [m] perimeter of the pipe cross section (needed only for non-circular pipes)
• shape_factor: shape factor, see friction_factor function
• head_factor: effective length multiplier, used to account for addition friction from flow development and additional friction such as pipe bends, entrance/exit lossses, etc.

Connectors:

• port_a: hydraulic port
• port_b: hydraulic port

FlowDivider(; n, name)

Reduces the flow from port_a to port_b by n. Useful for modeling parallel tubes efficiently by placing a FlowDivider on each end of a tube.

Parameters:

• n: divide flow from port_a to port_b by n

Connectors:

• port_a: full flow hydraulic port
• port_b: part flow hydraulic port

Valve(reversible = false; p_a_int, p_b_int, area_int, Cd, Cd_reverse = Cd, minimum_area = 0, name)

Valve with area input and discharge coefficient Cd defined by https://en.wikipedia.org/wiki/Dischargecoefficient. The `Cdreverse` parameter allows for directional flow restriction, making it possible to define a check valve.

Parameters:

• p_a_int: [Pa] initial pressure for port_a
• p_b_int: [Pa] initial pressure for port_b
• area_int: [m^2] initial valve opening
• Cd: discharge coefficient flowing from a → b
• Cd_reverse: discharge coefficient flowing from b → a
• minimum_area: when reversible = false applies a forced minimum area

Connectors:

• port_a: hydraulic port
• port_b: hydraulic port
• area: real input setting the valve area. When reversible = true, negative input reverses flow direction, otherwise a floor of minimum_area is enforced.

FixedVolume(; p_int, vol, name)

Fixed fluid volume.

Parameters:

• p_int: [Pa] initial pressure
• vol: [m^3] fixed volume

Connectors:

• port: hydraulic port

Volume(; x, dx=0, p, drho=0, dm=0, area, direction = 1, name)

Volume with moving wall with flange connector for converting hydraulic energy to 1D mechanical. The direction argument aligns the mechanical port with the hydraulic port, useful when connecting two dynamic volumes together in oppsing directions to create an actuator.

     ┌─────────────────┐ ───
     │                 │  ▲
                       │  │
dm ────►               │  │ area
                       │  │
     │                 │  ▼
     └─────────────────┤ ───
                       │
                       └─► x (= ∫ flange.v * direction)

Features:

• volume discretization with flow resistance and inertia: use N to control number of volume and resistance elements. Set N=0 to turn off volume discretization. See TubeBase for more information about flow resistance.
• minimum volume flow shutoff with damping and directional resistance. Use reversible=false when problem defines volume position x and solves for dm to prevent numerical instability.

Parameters:

volume

• p: [Pa] initial pressure

• area: [m^2] moving wall area

• x: [m] initial wall position

• dx=0: [m/s] initial wall velocity

• drho=0: [kg/m^3/s] initial density derivative

• dm=0: [kg/s] initial flow

• direction: [+/-1] applies the direction conversion from the flange to x

Connectors:

• port: hydraulic port
• flange: mechanical translational port

See also FixedVolume, DynamicVolume

DynamicVolume(reversible = false; p_int,  area, x_int = 0, x_max, x_min = 0, x_damp = x_min, direction = +1, perimeter = 2 * sqrt(area * pi), shape_factor = 64, head_factor = 1, Cd = 1e2, Cd_reverse = Cd, name)

Volume with moving wall with flange connector for converting hydraulic energy to 1D mechanical. The direction argument aligns the mechanical port with the hydraulic port, useful when connecting two dynamic volumes together in oppsing directions to create an actuator.

     ┌─────────────────┐ ───
     │                 │  ▲
                       │  │
dm ────►               │  │ area
                       │  │
     │                 │  ▼
     └─────────────────┤ ───
                       │
                       └─► x (= ∫ flange.v * direction)

Features:

• minimum volume flow shutoff with damping and directional resistance. Use reversible=false when problem defines volume position x and solves for dm to prevent numerical instability.

Parameters:

volume

• p_int: [Pa] initial pressure

• area: [m^2] moving wall area

• x_max: [m] max wall position, needed for volume discretization to apply the correct volume sizing as a function of x

• x_min: [m] wall position that shuts off flow and prevents negative volume.

• x_damp: [m] wall position that initiates a linear damping region before reaching full flow shut off. Helps provide a smooth end stop.

• direction: [+/-1] applies the direction conversion from the flange to x

flow resistance

• perimeter: [m] perimeter of the cross section (needed only for non-circular volumes)
• shape_factor: shape factor, see friction_factor function
• head_factor: effective length multiplier, used to account for addition friction from flow development and additional friction such as pipe bends, entrance/exit lossses, etc.

flow shut off and damping

• Cd: discharge coefficient for flow out of the volume. Note: area is 1m² when valve is fully open. Ensure this does not induce unwanted flow resistance.
• Cd_reverse: discharge coefficient for flow into the volume. Use a lower value to allow easy wall release, in some cases the wall can "stick".

Connectors:

• port: hydraulic port
• flange: mechanical translational port

SpoolValve(reversible = false; x_int, Cd, d, name)

Spool valve with x valve opening input as mechanical flange port and d diameter of orifice. See Valve for more information.

Parameters:

• x_int: [m] initial valve opening
• d: [m] orifice diameter
• Cd: discharge coefficient flowing from a → b

Connectors:

• port_a: hydraulic port
• port_b: hydraulic port
• flange: mechanical translational port

See Valve for more information.

SpoolValve2Way(reversible = false; m, g, x_int, Cd, d, name)

2-ways spool valve with 4 ports and spool mass. Fluid flow direction S → A and B → R when x is positive and S → B and A → R when x is negative.

Parameters:

• m: [kg] mass of the spool
• g: [m/s²] gravity field acting on the spool, positive value acts in the positive direction
• x_int: [m] initial valve opening
• d: [m] orifice diameter
• Cd: discharge coefficient flowing from s → a and b → r

Connectors:

• port_s: hydraulic port
• port_a: hydraulic port
• port_b: hydraulic port
• port_r: hydraulic port
• flange: mechanical translational port

See SpoolValve for more information.

Actuator(N, add_inertia = true, reversible = false;
    p_a_int,
    p_b_int,
    area_a,
    area_b,
    perimeter_a = 2 * sqrt(area_a * pi),
    perimeter_b = 2 * sqrt(area_b * pi),
    length_a_int,
    length_b_int,
    shape_factor_a = 64,
    shape_factor_b = 64,
    head_factor_a = 1,
    head_factor_b = 1,
    m,
    g,
    x_int = 0,
    minimum_volume_a = 0,
    minimum_volume_b = 0,
    damping_volume_a = minimum_volume_a,
    damping_volume_b = minimum_volume_b,
    Cd = 1e4,
    Cd_reverse = Cd,
    p_a_int,
    p_b_int,
    name)

Actuator made of two DynamicVolumes connected in opposite direction with body mass attached.

Features:

• volume discretization with flow resistance and inertia: use N to control number of volume and resistance elements. Set N=0 to turn off volume discretization. See TubeBase for more information about flow resistance.
• minimum volume flow shutoff with damping and directional resistance. Use reversible=false when problem defines volume position x and solves for dm to prevent numerical instability.

Parameters:

volume

• p_a_int: [Pa] initial pressure for port_a
• p_b_int: [Pa] initial pressure for port_b
• area_a: [m^2] moving wall area of volume A
• area_b: [m^2] moving wall area of volume B
• length_a_int: [m] initial wall position for A
• length_b_int: [m] initial wall position for b

mass

• m: [kg] mass of the body
• g: [m/s²] gravity field acting on the mass, positive value acts in the positive direction
• x_int: [m] initial flange position

flow resistance

• perimeter_a: [m] perimeter of the cross section A (needed only for non-circular volumes)
• perimeter_b: [m] perimeter of the cross section B (needed only for non-circular volumes)
• shape_factor_a: shape factor of A, see friction_factor function
• shape_factor_b: shape factor of B, see friction_factor function
• head_factor_a: effective length multiplier for A, used to account for addition friction from flow development and additional friction such as pipe bends, entrance/exit lossses, etc.
• head_factor_b: effective length multiplier for B, used to account for addition friction from flow development and additional friction such as pipe bends, entrance/exit lossses, etc.

flow shut off and damping

• minimum_volume_a: [m^3] minimum volume A that shuts off flow and prevents negative volume.
• minimum_volume_b: [m^3] minimum volume B that shuts off flow and prevents negative volume.
• damping_volume_a: [m^3] volume of A that initiates a linear damping region before reaching full flow shut off. Helps provide a smooth end stop.
• damping_volume_b: [m^3] volume of B that initiates a linear damping region before reaching full flow shut off. Helps provide a smooth end stop.
• Cd: discharge coefficient for flow out of the volume. Note: area is 1m² when valve is fully open. Ensure this does not induce unwanted flow resistance.
• Cd_reverse: discharge coefficient for flow into the volume. Use a lower value to allow easy wall release, in some cases the wall can "stick".

Connectors:

• port_a: hydraulic port
• port_b: hydraulic port
• flange: mechanical translational port

MassFlow(; name)

Hydraulic mass flow input source

Connectors:

• port: hydraulic port
• dm: real input

Pressure(; name)

input pressure source

Connectors:

• port: hydraulic port
• p: real input

FixedPressure(; p, name)

Fixed pressure source

Parameters:

• p: [Pa] set pressure (set by p argument)

Connectors:

• port: hydraulic port