added documentation

Author: Brad Carman

src/Hydraulic/IsothermalCompressible/components.jl

@@ -1,207 +1,232 @@
 """
-    Source(;name, p)
+    Source(; p, name)
 
 Fixed pressure source
 
 # Parameters:
-
-  - `p`: [Pa] set pressure
+- `p`: [Pa] set pressure (set by `p` argument)
 
 # Connectors:
-
-  - `port`: hydraulic port
+- `port`: hydraulic port
 """
-function Source(;name, p)
-    pars = @parameters begin
-        p = p
-    end
+@component function Source(; p, name)
+    pars = @parameters begin p = p end
 
     vars = []
-    
-    systems = @named begin
-        port = HydraulicPort(; p_int = p)
-    end
-    
+
+    systems = @named begin port = HydraulicPort(; p_int = p) end
+
     eqs = [
-        port.p ~ p
+        port.p ~ p,
     ]
 
     ODESystem(eqs, t, vars, pars; name, systems)
 end
 
+"""
+    InputSource(; p_int, name)
 
+Fixed pressure source
 
-function InputSource(;name, p_int)
-    pars = @parameters begin
-        p_int = p_int
-    end
+# Parameters:
+- `p_int`: [Pa] initial pressure (set by `p_int` argument)
+
+# Connectors:
+- `port`: hydraulic port
+"""
+@component function InputSource(; p_int, name)
+    pars = @parameters begin p_int = p_int end
 
     vars = []
-    
+
     systems = @named begin
         port = HydraulicPort(; p_int)
         input = RealInput()
     end
-    
+
     eqs = [
-        port.p ~ input.u
+        port.p ~ input.u,
     ]
 
     ODESystem(eqs, t, vars, pars; name, systems)
 end
 
-
 """
-    FixedVolume(fluid; name, vol, p_int)
+    FixedVolume(; vol, p_int, name)
 
-fixed fluid volume where `fluid` specifies the medium
+Fixed fluid volume.
 
 # Parameters:
-
-  - `vol`: [m^3] fixed volume
-  - `p_int`: [Pa] Initial pressure
-  
+- `vol`: [m^3] fixed volume
+- `p_int`: [Pa] initial pressure
 
 # Connectors:
-
-  - `port`: hydraulic port
+- `port`: hydraulic port
 """
-function FixedVolume(; name, fluid, vol, p_int)
+@component function FixedVolume(; vol, p_int, name)
     pars = @parameters begin
         vol = vol
         p_int = p_int
-        fluid=fluid
     end
 
+    systems = @named begin port = HydraulicPort(; p_int) end
+
     vars = @variables begin
-        rho(t) = density(fluid, p_int)
+        rho(t) = density(port, p_int)
         drho(t) = 0
     end
-    
-    systems = @named begin
-        port = HydraulicPort(; p_int)
-    end
 
     # let -------------------
     dm = port.dm
-    
-    eqs = [
-        D(rho) ~ drho
-        rho ~ density(fluid, port.p)
-        
-        dm ~ drho*vol 
-    ]
+
+    eqs = [D(rho) ~ drho
+           rho ~ density(port, port.p)
+           dm ~ drho * vol]
 
     ODESystem(eqs, t, vars, pars; name, systems)
 end
 
 """
-    LaminarResistance(fluid, shape=:circle; name, p_int, area, length, perimeter=2*sqrt(area*pi))
+    PipeBase(; p_int, area, length, perimeter=2*sqrt(area*pi), shape_factor=64, name)
 
-laminar pipe resistance
+Pipe segement which models purely the fully developed flow friction, ignoring any compressibility.
 
 # Parameters:
-
-  - `vol`: [m^3] fixed volume
-  - `p_int`: [Pa] Initial pressure
-  
+- `p_int`: [Pa] initial pressure (set by `p_int` argument)
+- `area`: [m^2] tube cross sectional area (set by `area` argument)
+- `length`: [m] length of the pipe (set by `length` argument)
+- `perimeter`: [m] perimeter of the pipe cross section (set by optional `perimeter` argument, needed only for non-circular pipes)
+- `Φ`: shape factor, see `friction_factor` function (set by optional `shape_factor` argument, needed only for non-circular pipes).  
 
 # Connectors:
-
-  - `port`: hydraulic port
+- `port_a`: hydraulic port
+- `port_b`: hydraulic port
 """
-function PipeBase(;name, fluid, shape=Shapes.circle, p_int, area, length, perimeter=2*sqrt(area*pi))
+@component function PipeBase(; p_int, area, length, perimeter = 2 * sqrt(area * pi),
+                             shape_factor = 64, name)
     pars = @parameters begin
         p_int = p_int
         area = area
         length = length
         perimeter = perimeter
-        fluid=fluid
-        shape=shape
+        Φ = shape_factor
     end
 
     vars = []
-    
+
     systems = @named begin
         port_a = HydraulicPort(; p_int)
         port_b = HydraulicPort(; p_int)
     end
-    
 
     # let ----------------------
     Δp = port_a.p - port_b.p
     dm = port_a.dm
-    p = (port_a.p + port_b.p)/2
 
-    d_h = 4*area/perimeter
+    d_h = 4 * area / perimeter
+
+    ρ = (density(port_a, port_a.p) + density(port_b, port_b.p)) / 2
+    μ = viscosity(port_a)
 
-    ρ = density(fluid, p)
-    μ = viscosity(fluid)
-    Φ = shape_factor(shape)
     f = friction_factor(dm, area, d_h, ρ, μ, Φ)
-    u = dm/(ρ*area)
+    u = dm / (ρ * area)
 
-    eqs = [        
-        Δp ~ 1/2 * ρ * u^2 * f * (length/d_h)
-        0 ~ port_a.dm + port_b.dm
-    ]
+    eqs = [Δp ~ 1 / 2 * ρ * u^2 * f * (length / d_h)
+           0 ~ port_a.dm + port_b.dm]
 
     ODESystem(eqs, t, vars, pars; name, systems)
 end
 
-function Pipe(N; name, fluid, shape=Shapes.circle, p_int, area, length, perimeter=2*sqrt(area*pi))
+"""
+    Pipe(N; p_int, area, length, perimeter=2*sqrt(area*pi), shape_factor=64, name)
+
+Pipe modeled with `N` segements which models the fully developed flow friction and compressibility.
 
-    @assert(N>1, "the pipe component must be defined with more than 1 segment (i.e. N>1), found N=$N")
+# Parameters:
+- `p_int`: [Pa] initial pressure (set by `p_int` argument)
+- `area`: [m^2] tube cross sectional area (set by `area` argument)
+- `length`: [m] length of the pipe (set by `length` argument)
+- `perimeter`: [m] perimeter of the pipe cross section (set by optional `perimeter` argument, needed only for non-circular pipes)
+- `Φ`: shape factor, see `friction_factor` function (set by optional `shape_factor` argument, needed only for non-circular pipes).  
+
+# Connectors:
+- `port_a`: hydraulic port
+- `port_b`: hydraulic port
+"""
+@component function Pipe(N; p_int, area, length, perimeter = 2 * sqrt(area * pi),
+                         shape_factor = 64, name)
+    @assert(N>1,
+            "the pipe component must be defined with more than 1 segment (i.e. N>1), found N=$N")
 
     pars = @parameters begin
         p_int = p_int
         area = area
         length = length
         perimeter = perimeter
-        fluid=fluid
-        shape=shape
+        Φ = shape_factor
     end
-    
+
     vars = []
-    
+
     ports = @named begin
         port_a = HydraulicPort(; p_int)
         port_b = HydraulicPort(; p_int)
     end
 
-
     pipe_bases = []
-    for i=1:N-1
-        x = PipeBase(;name=Symbol("p$i"), fluid=ParentScope(fluid), shape=ParentScope(shape), p_int=ParentScope(p_int), area=ParentScope(area), length=ParentScope(length)/(N-1), perimeter=ParentScope(perimeter))
+    for i in 1:(N - 1)
+        x = PipeBase(; name = Symbol("p$i"), shape_factor = ParentScope(Φ),
+                     p_int = ParentScope(p_int), area = ParentScope(area),
+                     length = ParentScope(length) / (N - 1),
+                     perimeter = ParentScope(perimeter))
         push!(pipe_bases, x)
     end
 
     volumes = []
-    for i=1:N
-        x = FixedVolume(; name=Symbol("v$i"), fluid=ParentScope(fluid), vol=ParentScope(area)*ParentScope(length)/N, p_int=ParentScope(p_int))
+    for i in 1:N
+        x = FixedVolume(; name = Symbol("v$i"),
+                        vol = ParentScope(area) * ParentScope(length) / N,
+                        p_int = ParentScope(p_int))
         push!(volumes, x)
     end
-    
 
-    eqs = [
-        connect(volumes[1].port, pipe_bases[1].port_a, port_a)
-        connect(volumes[end].port, pipe_bases[end].port_b, port_b)
-    ]
+    eqs = [connect(volumes[1].port, pipe_bases[1].port_a, port_a)
+           connect(volumes[end].port, pipe_bases[end].port_b, port_b)]
 
-    for i=2:N-1
-        eq = connect(volumes[i].port, pipe_bases[i-1].port_b, pipe_bases[i].port_a)
+    for i in 2:(N - 1)
+        eq = connect(volumes[i].port, pipe_bases[i - 1].port_b, pipe_bases[i].port_a)
         push!(eqs, eq)
     end
 
-
-    ODESystem(eqs, t, vars, pars; name, systems=[ports; pipe_bases; volumes])
+    ODESystem(eqs, t, vars, pars; name, systems = [ports; pipe_bases; volumes])
 end
 
+"""
+    DynamicVolume(; p_int, x_int=0, area, dead_volume=0, direction=+1, name)
+
+Volume with moving wall.  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.
+     _________
+    |         |
+   --> d.v.   |
+    |_________|         
+              └─► x (= ∫ flange.v * direction)
+
 
-function Actuator(direction; name, fluid, p_int, x_int, area, dead_volume)
+# Parameters:
+- `p_int`: [Pa] initial pressure (set by `p_int` argument)
+- `x_int`: [m] initial position of the moving wall (set by the `x_int` argument)
+- `area`: [m^2] moving wall area (set by the `area` argument)
+- `dead_volume`: [m^3] perimeter of the pipe cross section (set by optional `perimeter` argument, needed only for non-circular pipes)
+
+# Connectors:
+- `port`: hydraulic port
+- `flange`: mechanical translational port
+"""
+@component function DynamicVolume(; p_int, x_int = 0, area, dead_volume = 0, direction = +1,
+                                  name)
+    @assert (direction == +1)||(direction == -1) "direction arument must be +/-1, found $direction"
 
     pars = @parameters begin
-        fluid = fluid
         p_int = p_int
         x_int = x_int
         area = area
@@ -221,19 +246,14 @@ function Actuator(direction; name, fluid, p_int, x_int, area, dead_volume)
     end
 
     # let -------------
-    vol = dead_volume + area*x
+    vol = dead_volume + area * x
 
-    eqs = [
-        D(x) ~ dx
-        D(rho) ~ drho
-
-        dx ~ flange.v*direction
-        rho ~ density(fluid, port.p)
-        
-        port.dm ~ drho*vol + rho*area*dx
-        flange.f ~ -port.p*area*direction
-    ]
+    eqs = [D(x) ~ dx
+           D(rho) ~ drho
+           dx ~ flange.v * direction
+           rho ~ density(fluid, port.p)
+           port.dm ~ drho * vol + rho * area * dx
+           flange.f ~ -port.p * area * direction]
 
     ODESystem(eqs, t, vars, pars; name, systems)
 end
-