# Create Hydraulic Model

> Create Modelica models using the Hydraulic library with knowledge-graph-guided component selection and wiring. Use this skill whenever the user asks to create, build, design, or generate a hydraulic circuit or Modelica model using the Hydraulic library. Triggers on phrases like 'create a hydraulic model', 'build a circuit with a pump and cylinder', 'design a meter-in circuit', 'make a model with…

- **Type:** Skill
- **Install:** `agentstack add skill-wolframresearch-system-modeler-ai-toolkit-create-hydraulic-model`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [WolframResearch](https://agentstack.voostack.com/s/wolframresearch)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [WolframResearch](https://github.com/WolframResearch)
- **Source:** https://github.com/WolframResearch/system-modeler-ai-toolkit/tree/main/create-hydraulic-model
- **Website:** https://www.wolfram.com/system-modeler/

## Install

```sh
agentstack add skill-wolframresearch-system-modeler-ai-toolkit-create-hydraulic-model
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

```bash
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:

```bash
# 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:
```bash
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:

```bash
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:

```bash
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:

```modelica
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):

```bash
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, flange_a, flange_b**: 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](https://github.com/WolframResearch)
- **Source:** [WolframResearch/system-modeler-ai-toolkit](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-wolframresearch-system-modeler-ai-toolkit-create-hydraulic-model
- Seller: https://agentstack.voostack.com/s/wolframresearch
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.