Create Hydraulic Model

Create Hydraulic Model (Graph RAG Guided)

This skill uses a knowledge graph of the Hydraulic Modelica library to guide the user through creating valid hydraulic circuit models. The graph (built from Hydraulic 2.1) contains 168 parsed components with their ports, parameters, inheritance, and 60 validated connection patterns extracted from the library's composite models and 18 example circuits.

Before you run anything

The query commands below run python -m Hydraulic.main …; the optional validation step (Step 7) additionally drives the shared launcher. For the Windows-vs-Unix shell/Python rules (PowerShell on Windows, python vs python3) and launcher conventions, see [the shared-conventions appendix at the end of this file](#appendix-shared-conventions-for-the-modelica-skills) — the launcher-specific parts (temp dirs, JSON output, MSL, --load-library) only matter once you validate.

Knowledge Graph (bundled)

The Graph RAG dataset and query module ship inside this skill as the Hydraulic/ Python package — there is nothing external to locate. The query path reads the prebuilt graph in Hydraulic/data/graph.json; it does not need the Modelica library and does not re-parse anything, so it works wherever the skill is installed.

• Requirement: networkx — but you don't install it by hand. Hydraulic.main

self-provisions it into a managed venv on first run (it never touches system Python). To pre-warm: python3 "/bootstrap_env.py" networkx.

• Run the query module with this skill's own directory (the folder

containing this SKILL.md) as the working directory, so the package resolves as Hydraulic.

Query Commands

Run from this skill's directory (` below — the folder that contains this SKILL.md) so the Hydraulic package is importable. Use python instead of python3` on Windows if that's what's on PATH.

cd ""

# Search for components by keyword
python3 -m Hydraulic.main --query "pump"

# Get the full effective interface of a component (ports + parameters, incl. inherited)
python3 -m Hydraulic.main --details "CylinderDouble"

# Find all components that extend an interface
python3 -m Hydraulic.main --interface "FourPort"

# List all example circuits
python3 -m Hydraulic.main --examples

# Get RAG context for a natural language query
python3 -m Hydraulic.main --rag "pressure control circuit"

(Use the absolute path to this skill's directory for ``.)

Validating & Simulating the Generated Model

Generation itself only needs the bundled graph (above). To flatten, validate, or simulate a generated model you drive WSMKernelX through the shared launcher — the same one every other Modelica skill uses. Read [the shared-conventions appendix at the end of this file](#appendix-shared-conventions-for-the-modelica-skills) first for launcher resolution, the Windows-vs-Unix shell/Python rules, the temp-dir/cleanup conventions, the JSON-array output gotcha, and the MSL 4.x dialect notes.

The model extends Hydraulic.…, so the Hydraulic library must be loaded alongside it. Do not locate or pass the path by hand — add --load-library Hydraulic to any validate / simulate / diagnose run and the launcher finds it (pin a version with Hydraulic==2.1; run --mode libraries to see what is installed). Resolution details and overrides: [Appendix → Using non-MSL libraries](#using-non-msl-libraries-hydraulic-and-other-installed-libraries).

Mind the library version. The bundled graph is built from Hydraulic 2.1. If --mode libraries shows a different installed version, treat graph answers as hints rather than ground truth — component or parameter names may have drifted — and validate the generated model early so any mismatch surfaces immediately.

Guided Workflow

Follow these steps in order, confirming with the user at each step before proceeding.

Step 1: Understand the Circuit Requirements

Parse the user's request (from $ARGUMENTS if invoked as /create-hydraulic-model , or from the conversation).

Identify:

• Primary function: What should the circuit do? (move a load, control flow, hold pressure, transmit power, etc.)
• Actuator type: Translation (cylinder) or rotation (motor)?
• Control needs: Directional control? Pressure limiting? Flow control? Sequence?
• Any specific components the user mentioned by name

Step 2: Query the Knowledge Graph for Relevant Components

Based on the requirements, run targeted queries:

# For the main actuator
python -m Hydraulic.main --details "CylinderDouble"   # if translational
python -m Hydraulic.main --details "Motor"             # if rotational

# For the power source
python -m Hydraulic.main --details "Pump"

# For valves — find what's available
python -m Hydraulic.main --interface "FourPort"        # directional control valves
python -m Hydraulic.main --interface "ThreePort"       # pressure control / 3-way valves
python -m Hydraulic.main --interface "TwoPortStatic_2" # restrictions, throttles, filters

# For similar example circuits
python -m Hydraulic.main --rag ""

Also read the entities.json directly to get parameter defaults:

python -c "
import json
with open('Hydraulic/data/entities.json') as f:
    entities = json.load(f)
for e in entities:
    if e['name'] == 'COMPONENT_NAME':
        print(json.dumps(e, indent=2))
        break
"

Step 3: Present Component Selection to User

Show the user a table of recommended components:

Proposed Components:
| Role              | Component                          | Description                    |
|-------------------|------------------------------------|--------------------------------|
| Power source      | Hydraulic.PumpsAndMotors.Pump      | Fixed displacement pump        |
| Actuator          | Hydraulic.Cylinders.CylinderDouble | Double-acting cylinder         |
| Direction control | Hydraulic....PCVE43ClosedCenter    | 4/3 proportional valve         |
| Pressure relief   | Hydraulic....PressureReliefValve   | System pressure limiter        |
| Tank (supply)     | Hydraulic.LiquidContainers.Tank    | Constant pressure reservoir    |
| Tank (return)     | Hydraulic.LiquidContainers.Tank    | Return line reservoir          |
| Speed source      | Modelica...ConstantSpeed           | Drives the pump shaft          |
| Load              | Modelica...Mass                    | Translational mass load        |
| Control signal    | Modelica.Blocks.Sources.Step       | Step input for valve command   |

Ask the user:

• "Does this component selection look right?"
• "Would you like to add, remove, or swap any components?"
• "Any specific valve type preference?" (show available options if relevant)

Wait for user confirmation before proceeding.

Step 4: Propose Connections

Query example circuits that use similar components to find validated connection patterns:

python -m Hydraulic.main --rag "connect pump cylinder valve"

Present the proposed wiring to the user. Group by domain:

Proposed Connections:

Hydraulic (blue):
  1. tank1.port          -> pump.port_a          (tank feeds pump inlet)
  2. pump.port_b         -> controlValve.port_p  (pump pressure to valve P port)
  3. controlValve.port_a -> cylinder.port_a       (valve A to cylinder A)
  4. controlValve.port_b -> cylinder.port_b       (valve B to cylinder B)  
  5. controlValve.port_t -> tank2.port            (valve T to return tank)
  6. reliefValve.port_a  -> pump.port_b           (relief across pump output)
  7. reliefValve.port_b  -> tank3.port            (relief to tank)

Mechanical (green):
  8. constantSpeed.flange -> pump.flange          (speed source drives pump)
  9. cylinder.flange_b    -> mass.flange_a        (cylinder moves mass)

Signal (blue):
  10. step.y -> controlValve.u1                   (command signal to valve)
  11. const.y -> controlValve.u2                   (zero signal to valve u2)

Ask the user: "Does this wiring look correct? Any connections to add or change?"

Wait for user confirmation before proceeding.

Step 5: Configure Parameters

For each component, show key parameters with defaults. Read these from the knowledge graph:

python -m Hydraulic.main --details "Pump"
python -m Hydraulic.main --details "CylinderDouble"
# etc.

Present a parameter table:

Key Parameters (defaults shown — override any you want):

Pump:
  D = 5e-05 [m^3/rev]  "Displacement"

CylinderDouble:
  diameterPiston = 0.05 [m]
  diameterRod_a  = 0.005 [m]
  lengthHousing  = 0.5 [m]
  lengthPiston   = 0.05 [m]
  lengthRod_a    = 0.5 [m]
  Vdead_a        = 1e-05 [m^3]
  mPiston        = 10 [kg]

PressureReliefValve:
  pMin = 20000000 [Pa]  "Opening pressure (200 bar)"

Mass:
  m = 100 [kg]

ConstantSpeed:
  w_fixed = 100 [rad/s]

Simulation:
  StopTime = 2 [s]

Ask: "Want to change any parameter values?"

Wait for user confirmation before proceeding.

Units. Hydraulic models are SI (pressure in Pa, flow in m³/s) and use displayUnit for friendly labels (e.g. bar, L/min):

• A parameter modifier that carries displayUnit must take a literal value:

pMin(displayUnit = "bar") = 20000000.0, not = 200*1e5. An arithmetic expression silently disables the displayUnit conversion in WSM, so the GUI shows the raw SI number. Compute the SI value yourself and write it as a literal (keep the readable origin in a comment if helpful).

• Signals arriving through a connector are already in SI base units — never rescale at the wiring

site (*1e-5, /60000). Declare SI types with displayUnit = "…" and let the unit conversion happen for display only.

Step 6: Generate the .mo File

Ask the user where to save the model:

• Suggested default: an Examples/ subfolder of the user's own Modelica library
• Or any user-specified path

Generate the complete Modelica model following this template structure:

within ;

model  ""
  extends Hydraulic.Icons.Example;
  extends Hydraulic.Media.BaseModel;

  // Components — pass medium = medium only if  extends Hydraulic.Media.BaseModel (e.g. not Tank)
   (, medium = medium)
    annotation(Placement(visible = true, transformation(origin = {x, y},
      extent = {{-10, -10}, {10, 10}}, rotation = 0)));
  
  // Parameters
  parameter SI.Pressure openingPressure = 20000000.0 "Relief valve opening pressure";
  
equation
  // Hydraulic connections
  connect(., .)
    annotation(Line(visible = true, origin = {0, 0},
      points = {{0, 0}, {0, 0}}, color = {0, 170, 255}));
  
  // Mechanical connections
  connect(., .)
    annotation(Line(visible = true, origin = {0, 0},
      points = {{0, 0}, {0, 0}}, color = {0, 127, 0}));
  
  // Signal connections
  connect(.y, .u1)
    annotation(Line(visible = true, origin = {0, 0},
      points = {{0, 0}, {0, 0}}, color = {0, 0, 127}));

  annotation(
    experiment(StopTime = , __Wolfram_NumberOfIntervals = 2000,
      __Wolfram_Algorithm = "cvodes"),
    Documentation(info = ""));
end ;

Critical rules for valid .mo files:

1. Every Hydraulic component that extends Hydraulic.Media.BaseModel needs medium = medium in its parameter list; components that don't (e.g. Tank) must NOT receive it — check with --details
2. extends Hydraulic.Media.BaseModel; provides the medium record
3. extends Hydraulic.Icons.Example; gives the example icon
4. Use color {0, 170, 255} for hydraulic connections
5. Use color {0, 127, 0} for mechanical connections
6. Use color {0, 0, 127} for signal connections
7. Every connect() needs a Line annotation (even with dummy points)
8. The within path must match the file's location in the package hierarchy
9. Pump needs phi.fixed = true, dp.fixed = true for proper initialization
10. CylinderDouble needs pA.fixed = true, pB.fixed = true for initialization

Layout conventions (approximate placement origins for a clean diagram):

• Tanks: bottom row, y = -70
• Pump: left side, y = -40
• Relief valve: near pump, y = -40
• Directional valve: center, y = 10
• Cylinder: upper area, y = 50
• Mass/load: right side, y = 50
• Signal sources: far left, various y
• Speed source: far left, y = -40

Write the file using the Write tool.

Step 7: Offer Validation

After writing the file, ask: "Would you like me to validate this model using the Modelica compiler?"

If yes, use the validate-modelica (or simulate-modelica) skill on the generated file. Because the model uses the Hydraulic library, add --load-library Hydraulic so the launcher loads it alongside the model (MSL is automatic):

python3 "/wsm_run.py" --mode validate \
  --model "" --name  --load-library Hydraulic --timeout 120

(Use python on Windows. See "Validating & Simulating the Generated Model" above and [the shared-conventions appendix](#appendix-shared-conventions-for-the-modelica-skills) for launcher resolution and temp-dir/cleanup conventions.) A clean run reports flatten=Pass.

Component Quick Reference

Common Circuit Patterns

Basic servo (translate): Pump + PressureReliefValve + PCVE43 + CylinderDouble + Mass Basic servo (rotate): Pump + PressureReliefValve + PCVE43 + Motor + Inertia Meter-in flow control: Add FixedTurbulentThrottle before directional valve Meter-out flow control: Add FixedTurbulentThrottle after directional valve Load holding: Add CounterBalanceValve between valve and cylinder Accumulator circuit: Add CheckValve + OneWayFlowControlValve + GasChargedAccumulator Sequence circuit: Add PilotOperatedSequenceValve between stages Pressure reducing: Add PressureReducingValve for sub-circuit pressure limiting

Valve Naming Convention

• DCVE: Directional Control Valve, Electrically actuated (conventional solenoid)
• PCVE: Proportional Control Valve, Electrically actuated (proportional solenoid)
• DCVH: Directional Control Valve, Hydraulically actuated (pilot operated)
• DCVM: Directional Control Valve, Mechanically actuated
• 42: 4 ports, 2 positions
• 43: 4 ports, 3 positions
• 32: 3 ports, 2 positions
• 63: 6 ports, 3 positions
• Center type suffix: ClosedCenter, OpenCenter, TandemCenter, FloatingCenter, DiagonalCenter

Port Naming Convention

• port_p: Pressure supply (from pump)
• port_t: Tank return
• port_a: Load port A (cylinder side A)
• port_b: Load port B (cylinder side B)
• port_pilot: Pilot pressure input
• u1, u2: Electrical/signal control inputs
• flange, flangea, flangeb: Mechanical connections
• port: Single hydraulic port (tanks, accumulators, sensors)

Required Modelica Standard Library Components

• Modelica.Mechanics.Rotational.Sources.ConstantSpeed — drives pump shaft
• Modelica.Mechanics.Translational.Components.Mass — translational load
• Modelica.Mechanics.Rotational.Components.Inertia — rotational load
• Modelica.Blocks.Sources.Step — step signal for valve command
• Modelica.Blocks.Sources.Constant — constant signal (e.g., k=0 for valve u2)
• Modelica.Blocks.Sources.Ramp — ramp signal
• Modelica.Blocks.Math.Min / Max / Add — signal processing
• Modelica.Blocks.Math.BooleanToReal — convert switch to proportional signal

---

Appendix: shared conventions for the Modelica skills

> Shared by every Modelica skill that drives WSMKernelX through the > bundled launcher; inlined here at release time. For the CLI/option > reference, environment variables (WSM_HOME, WSM_VSDEVCMD), > install discovery, and the analysis scripts, see > [../scripts/README.md](../scripts/README.md).

Locating the launcher

` (used throughout the skills) is the shared scripts/` folder. Some installs symlink the skill directories without it, so resolve it in this order and use the first that exists:

1. $WSM_SKILLS_SCRIPTS (bash) or $env:WSM_SKILLS_SCRIPTS (PowerShell), if set.
2. ../scripts relative to the skill directory — in a normal install

`../scripts/wsm

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: WolframResearch
• Source: WolframResearch/system-modeler-ai-toolkit
• License: MIT
• Homepage: https://www.wolfram.com/system-modeler/

Install and usage instructions live in the source repository linked above.