20. AGX Hydraulics

agxHydraulics is a library for modeling a hydraulic system. For code examples, look into the C++ (tutorials/agxOSG) and Python (data/python/tutorials) tutorials.

Hydraulics is the technology that deals with the generation, control and transmission of power using pressurized liquids. The AGX Hydraulics library allows for fast, accurate and stable simulation of hydraulics components in real time. It provides hydraulic components such as pumps, pipes, flow control valves, restrictions and actuators.

The hydraulics library is built upon the AGX PowerLine framework and designed to integrate with both the drive train and the mechanical system. It provides new types of Units and Connectors that can be inserted into the same power line graph as the Units and Connectors already available.

Power can be generated using an electric motor or combustion engine and transmitted through a drive train to a hydraulic pump which converts torque in the drive train to pressure in the hydraulics circuit. The pressure can then be transmitted through the hydraulics to actuators that interact with the mechanical system, or to hydraulic motors in order to transition back to a drive train.

Using the combined functionality of the power line, hydraulics and mechanics of AGX Dynamics it is possible to model and simulate complex systems such as an excavator, a crane, an offshore winch or similar.

A number of quantities can be read from the simulation, including pressure at junctions and couplings, flow rates through pipes and other components, fluid compression in pipes and junctions, and torques at pumps and motors.

20.1. Components

Table 20.1 Hydraulic components

Name	Type	Description
Accumulator	FlowUnit	Spring loaded fluid container that only accepts connections on the input side. Is filled with fluid when the input pressure is higher than the internal pressure and emptied when the input pressure is lower. Often used in conjunction with a stop valve to control filling/emptying.
CheckValve	FlowUnit	Allows flow in one direction only. Flow in the other direction is blocked. Acts like a regular pipe when the flow is in the allowed direction. Can be used to prevent actuator collapse when the working pressure is not enough to lift or hold a load.
ConstantFlowValve	FlowUnit	Has two modes. Limits the flow rate, in absolute value, to be less than some given maximum, or enforces a given flow rate. Acts like a regular pipe when in the limiting mode and the flow rate is within bounds. Acts like a pressure source when in the pumping mode.
FlowConnector	Pressure Connector	The basic hydraulic junction. Connect any type of FlowUnit and it will distribute the incoming flow among all connected FlowUnits.
Motor	Rotational Flow Connector	Connector that converts hydraulic flow into shaft rotation. The FlowUnit connected to the input becomes the fluid chamber and the RotationalUnit connected to the output becomes the motor shaft.
NeedleValve	FlowUnit	A controllable orifice opening. Used much like a pipe, but can be used to dynamically and continuously open and close a restriction. The continuous version of the stop valve.
Pipe	FlowUnit	The most basic FlowUnit. Moves fluid between other components.
PistonActuator	Translational Actuator	Models a hydraulic piston. Forms the interface between the 1-DoF hydraulics and the 6-DoF mechanical world.
Pump	Connector	Connector that converts shaft rotation into hydraulic flow. The RotationalUnit connected to the input becomes the pump shaft and the FlowUnit connected to the output becomes the pump chamber.
ReliefValve	Unit	Multiple orificed component with one input, one output and a number of drains. The drains remain closed until the pressure in the relief valve exceeds the configured cracking pressure, at which point a number of drains are opened depending on the actual pressure in the relief valve. If the pressure is at or above the configured fully open pressure then all drains open.
SpoolValve	Connector	Discrete directional control valve. Accepts any number of connected FlowUnits and can create links between them in arbitrary ways. Used to direct flow from (multiple) sources to (multiple) users.
StopValve	FlowUnit	A valve that is either open or closed. The binary version of the needle valve.
Variable Displacement Pump	Pressure Connector	A pressure regulated pump. Has a default displacement that is in effect as long as the pressure at the pump is below the configured deadhead pressure. The displacement decreases as the pressure increases from the deadhead pressure to the cutoff pressure. At and above the deadhead pressure the displacement becomes zero and the pump passive.

20.2. Class structure

The hydraulics library is built upon the power line framework and the abstractions that it provides. The hydraulics components are implemented as subclasses of agxPowerLine::Unit, agxPowerLine::Connector or agxPowerLine::Actuator. Many hydraulic units inherit from agxPowerLine::Unit via the agxHydraulics::FlowUnit class. Similarly, many connectors in the AGX Hydraulics library inherit from agxPowerLine::Connector via agxHydraulics::PressureConnector.

20.2.1. FlowUnit

A power line is a graph of Units connected by Connectors. Units carry motion, which is managed by PhysicalDimensions. The motion that the hydraulic units carry is the motion of the fluid itself. We call the hydraulic units FlowUnits, and the physical dimension of flow is defined by the FlowDimension class. It represents the actual flow in and out of a FlowUnit.

As described in the DriveTrain section, all PhysicalDimensions define a value, a gradient, and a mass property. The fluid flow rate, measured in units of volume per time, is the gradient of the flow dimension. The flow dimension’s value is the total volume that has passed through the unit. This value may be inaccurate and should not be used. The mass property of a FlowDimension is not the mass of the fluid itself, but rather the resistance to change in flow rate given a pressure differential over the Unit. It increases with the length of the component and decreases with the area.

FlowUnits have a direction and an input and an output side. Forward, or positive, flow is defined as fluid entering at the input side and leaving at the output side. It is not required that FlowUnits are connected output-to-input. The effect of connecting input-to-input or output-to-output is that the two FlowUnits will have flow rates with opposite signs. Some hydraulic components behave differently depending on if it receives flow at the input or the output side, so it is important to keep track of the flow direction through each component.

The most basic FlowUnit is the Pipe, but several other hydraulic components are implemented as subclasses of FlowUnit as well. Hydraulic components that are not FlowUnits tend to inherit from PressureConnector instead.

20.2.2. PressureConnector

Connectors that propagate pressure through the FlowUnit graph are called pressure connectors. They all have a getPressure method, which returns the last pressure that the connector exerted on the connected FlowUnits.

An important subclass of PressureConnector is the FlowConnector. A FlowUnit can connect to many PressureConnectors, but no more than one FlowConnector per side. FlowConnectors are used to move fluid between FlowUnits. It ensures that all fluid that enters the FlowConnector from some connected FlowUnit is accounted for as flow through the other FlowUnits connected to the same FlowConnector.

20.2.3. Actuator

Actuators form the bridge between the one-dimensional world of the power line and the six-dimensional mechanical world of regular AGX simulations. An Actuator is always associated with a regular AGX Dynamics constraint which defines the operation of the Actuator. An Actuator associated with a Hinge will cause rotation around the hinge axis and an Actuator associated with a Prismatic will cause translational motion along the prismatic axis.

20.3. Building circuits

In this section a simple example circuit is built and the required steps are demonstrated. The construction is split into three parts: flow control, translational actuation and pressure generation.

20.3.1. Foundation Setup

The components of a hydraulic circuit must be part of a PowerLine object, which must be added to a simulation.

agxSDK::SimulationRef simulation = new agxSDK::Simulation();
agxPowerLine::PowerLineRef powerLine = new agxPowerLine::PowerLine();
simulation->add(powerLine);

20.3.2. Connecting FlowUnits

The agxHydraulics library provides a number of hydraulic components that can be connected together to create the hydraulic circuit. The simplest one is the pipe. The agxHydraulics::Pipe constructor takes the pipe’s length and area as arguments, along with the fluid density.

This example uses the SI unit system, but that is not a general requirement. See separate section below.

agx::Real length(1);
agx::Real area(0.005);
agx::Real density(800);
agxHydraulics::PipeRef pipe = new agxHydraulics::Pipe(length, area, density);

Hydraulic components are joined together using FlowConnectors. A FlowConnector represents a junction where multiple pipes and other FlowUnits join. It cannot be connected to any other type of unit.

agxHydraulics::FlowConnectorRef junction = new agxHydraulics::FlowConnector();

We attach the pipe to the junction using the FlowConnector::connect method. The connector side argument is irrelevant for this particular type of connector, but the unit side argument is important. It specifies the side of the FlowUnit that is to be connected and thus also the direction of flow through the unit. In the following example we connect the junction’s input side to the output side of the pipe.

junction->connect(agxPowerLine::INPUT, agxPowerLine::OUTPUT, pipe);

Another type of FlowUnit is the stop valve. It is a manually operated valve that is either fully open or fully closed.

agxHydraulics::StopValveUnitRef stop =
    new agxHydraulics::StopValveUnit(length, area, density);

By connecting the input side of the stop valve to the same junction that the output side of the pipe is connected to we have told the system that any flow that leaves the output side of the pipe should enter the input side of the stop valve.

junction->connect(agxPowerLine::OUTPUT, agxPowerLine::INPUT, stop);

By creating additional units and connectors it is possible to create arbitrary graphs; including forks, loops, joins and connections to tank. A requirement is that a FlowUnit may only have at most a single FlowConnector at each side. Any FlowUnit side that is not connected to anything, such as the pipe input in the example, is implicitly connected to the tank and will be subjected to tank pressure. The tank pressure is set globally.

agxHydraulics::utils::setTankPressure(agx::Real(1e5));

The components must be added to the power line for the circuit to be included in the simulation. Adding one unit will bring with it all connected units into the PowerLine, and additional Units connected later will be added as well.

powerLine->add(pipe);

20.3.3. Coupling to mechanical constraints

The flow control part of the circuit is described above. The next part is actuation, which in the example is a hydraulic cylinder. Actuation, in this context, refers to the transition from the one dimensional hydraulics domain to the six dimensional mechanics domain. The interface for this transition is always a regular AGX dynamics constraint. The presence of pressure in the hydraulics at the actuator is translated into a force or torque on the mechanical bodies according to the configuration of the constraint, and vice versa. The force or torque acts in the non-constrained degree of freedom of the AGX Dynamics constraint.

The example at hand contains a hydraulic cylinder. The class in the AGX Hydraulics library that provides that functionality is agxHydraulics::PistonActuator. It is a type of translational actuator that is created from a prismatic or a distance joint. Here it is assumed that a prismatic has been created previously.

agx::PrismaticRef prismatic = ...;

The details of the PistonActuator creation are not required for this discussion.

agxHydraulics::PistonActuatorRef cylinder =
                 new agxHydraulics::PistonActuator(prismatic, ...);

Actuators are connected to the hydraulics circuit in the same way as Units. Instead of explicitly creating and connecting a FlowConnector we make use of implicit connector creation. When two FlowUnits are connected in the following manner the system either creates a new FlowConnector or uses one that has already been created for the FlowUnit sides being connected. If both sides already have a FlowConnector then they are merged into one, moving all connections from one of them to the other.

stop->connect(agxPowerLine::OUTPUT, agxPowerLine::INPUT, cylinder);

The second argument controls which side of the actuator the unit on which the call is made should be connected to. For a PistonActuator this selects one of the two chambers. Flow into the input side extends the piston, while flow into the output side compresses it. The coupling is two-way, so any force acting along the cylinder direction on the two bodies that the constraint is attached to will cause a pressure increase in one of the cylinder chambers, and any relative movement of the two bodies in the same direction will cause a flow of fluid through the cylinder.

20.3.4. Coupling to the power line

The hydraulics library provides a number of Connectors that bridge between a drive train and the hydraulics. The Pump is one such component. It accepts a RotationalUnit at its input and a FlowUnit at its output and converts torques on the input into pressures at the output. The hydraulic motor performs the opposite operation. It accepts a single FlowUnit input and a single RotationalUnit output.

Both pumps and motors have a property that defines the conversion ratio when translating between angular velocity and flow rate, called the displacement. The displacement describe the volume of fluid moved per radian of rotation of the RotationalDimension. A pump with a displacement of one will produce one unit of pressure for every unit of torque supplied at the input, and it will move, on average, one unit of volume for every radian that the input unit is rotated. With a displacement \(\propto\) the pump will produce \(\propto\) units of flow for every radian of rotation at the input, and generate \(\frac{1}{\propto}\) units of pressure for every unit of torque that is applied at the input. When using the SI unit system, it is common for pumps to have a displacement less than one.

The example circuit contains an engine and a pump, but no motor yet. Details for how to construct and configure an engine is provided in the AGX DriveTrain section.

agxModel::HighLevelEngineRef engine = ...;

The pump constructor takes as its only argument the pump displacement.

agx::Real displacement(0.01);
agxHydraulics::PumpRef pump = new agxHydraulics::Pump(displacement);

The pump is connected to the engine and the pipe in a way similar to the way the FlowConnector was connected between the pipe and the stop valve, with the difference that here we don’t explicitly suppliy the sides to connect. By default the output side of the first component is connected to the input side of the second component.

engine->connect(pump);
pump->connect(pipe);

The pipe has now, in essence, been turned into a pump. The pipe itself represents the fluid chamber inside the pump.

20.4. Run time system manipulation

Many of the hydraulic components in the library can be manipulated during runtime through their respective APIs. For some components this is an essential part of their operation. This is exemplified in the example circuit in the previous section by the stop valve whose main purpose is to open and close based on user input or some form of control logic. Examples of other properties that can be changed during runtime is pump and motor displacement, check valve orientation, relief valve pressure settings and constant flow valve target flow rate.

20.5. Data extraction

The state of each individual component can be inspected using each component’s respective API. The example circuit constructed in the Building circuits section is used below.

20.5.1. Pressure

Similar to how flow rate is a property of the FlowUnits, pressure is a property of the Connectors. The toolkit does not track pressures along a pipe, only at its end points. To read the pressure at a junction use the FlowConnector’s getPressure method.

agx::Real sourcePressure = junction->getPressure();

The call above will return the pressure at the pump outlet, i.e., the pressure where the stop valve is connected to the pump pipe. The pressure at any FlowUnit side can be read by first fetching the FlowConnector that the side is connected to. The following statement is equivalent to the previous one.

agx::Real sourcePressure = stop->getInputFlowConnector()->getPressure();

This technique can be used to read the pressure at locations where the FlowConnector was implicitly created, such as between the stop valve and the hydraulic cylinder in the example.

agx::Real workingPressure = stop->getOutputFlowConnector()->getPressure();

Be aware that not all FlowUnit sides has a connected FlowConnector and in these cases nullptr will be returned.

The pump connector is another subclass of PressureConnector and can therefore also return a pressure. The pressure returned is the pressure that the pump contributes to the system and not the pressure within the FlowUnit that the pump is connected to which will include pressures from connected neighboring pipes as well.

20.5.2. FlowRate

Flow rate is a property of the FlowUnits and are accessed using the getFlowRate method.

agx::Real flowRate = pipe->getFlowRate();

The flow rate is measured in units of volume per unit time. The toolkit does not track the flow velocity of the fluid, but the average flow velocity can be calculated by dividing the flow rate with the area of the FlowUnit.

There is no flow rate associated with FlowConnectors and, unlike the corresponding situation with pressure, there is no obvious way to find a FlowUnit to read the value from since a FlowConnector may be attached to any number of FlowUnits and the FlowUnits may be attached in any direction.

20.6. Units of measurement

It is possible to use any set of units as long as the choice is consistent across entire simulation spanning drive train, hydraulics and mechanics. This means that if geometry dimensions and rigid body positions are given in meters then FlowUnit areas must be given in meters as well, and reported flow rates will be in cubic meters per unit time.

Some helper functions, such as the RPM conversions, assume that SI units are used.

20.7. Parameter configuration

• Density - The density of the fluid, in units of mass per unit volume.

• Viscosity - The kinematic viscosity of the fluid, in units of area per time. The viscosity has a strong influence on the pressure loss over pipes, with zero viscosity resulting in no pressure loss at steady state.

• FlowConnector compliance - The compliance of the constraint held by the FlowConnector controls the compressibility of the system. The FlowConnectors will flex under pressure, which represents the flexibility of the junction itself, the expansion of the neighboring pipes and the compressibility of the fluid in those pipes. It is measured in units of volume per unit pressure.

• FlowConnector damping - Parameter that controls the rate at which pipe, junction and fluid deformations due to pressure variations are created and restored.

• Displacement - Pumps and motors have a displacement parameter that defines the relationship between flow rate in the chamber and the rotation of the shaft.

• Flow coefficient - The flow coefficient is currently only configurable for the needle valve. It is a measure of how efficiently fluid can pass through a component. The smaller this value is, the greater effect from the needle valve.

• Tank pressure - The pressure that any unconnected, i.e., tank connected, FlowUnit side is subjected to.

• …

20.8. Known limitations and assumptions

• Cavitation/vacuum inside pipes. The model assumes that all pipes and other components are always full with fluid and the constraints will ensure that this is the case. This may produce unrealistic pressures in cases where a real-world system would have produced cavitation and this may show up as negative pressures in the FlowConnectors. Common cases where this occurs is when the pump and load is working in the same direction and the pump is unable to keep up, e.g. a hydraulic cylinder is being extended faster than the pump can supply fluid and cavitation would be formed in the cylinder. Another scenario is a stop valve being closed while there is a large flow rate going through it.

• Gravity is ignored. Components don’t have elevation and all pipes are laid out horizontally.

• Assumes circular pipe cross sections and uniform area over the entire pipe.

• Does not take geometry of junctions into account. Cannot model bends or multi-pipe junctions where the angles between the pipes are important.

• No heat simulation.

20.9. Troubleshooting

The following is a listing of common causes of malfunctioning hydraulic simulations.

• Missing PowerLine::add.

• Misconfigured input/output side of unit.

• Valve mistakenly closed.

• Illegal connection (pump or motor backwards, connecting to nullptr, …).

• Zero displacement for pump/motor. Watch out for integer division.

• PistonActuator created from Prismatic without a properly configured range.

• Always check return values.