-------------------------------------------------------------------------------
-- Copyright (c) 2001 Mentor Graphics Corporation
--
-- This model is a component of the Mentor Graphics VHDL-AMS educational open 
-- source model library, and is covered by this license agreement. This model,
-- including any updates, modifications, revisions, copies, and documentation 
-- are copyrighted works of Mentor Graphics. USE OF THIS MODEL INDICATES YOUR 
-- COMPLETE AND UNCONDITIONAL ACCEPTANCE OF THE TERMS AND CONDITIONS SET FORTH
-- IN THIS LICENSE AGREEMENT.  Mentor Graphics grants you a non-exclusive 
-- license to use, reproduce, modify and distribute this model, provided that:
-- (a) no fee or other consideration is charged for any distribution except 
-- compilations distributed in accordance with Section (d) of this license 
-- agreement; (b) the comment text embedded in this model is included verbatim
-- in each copy of this model made or distributed by you, whether or not such 
-- version is modified; (c) any modified version must include a conspicuous 
-- notice that this model has been modified and the date of modification; and 
-- (d) any compilations sold by you that include this model must include a 
-- conspicuous notice that this model is available from Mentor Graphics in its
-- original form at no charge.
--
-- THIS MODEL IS LICENSED TO YOU "AS IS" AND WITH NO WARRANTIES, EXPRESS OR 
-- IMPLIED.  MENTOR GRAPHICS SPECIFICALLY DISCLAIMS ALL IMPLIED WARRANTIES OF 
-- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  MENTOR GRAPHICS SHALL
-- HAVE NO RESPONSIBILITY FOR ANY DAMAGES WHATSOEVER.
-------------------------------------------------------------------------------
-- File       : valve.vhd
-- Author     : Mentor Graphics
-- Created    : 2001-06-16
-- Last update: 2003-05-13
-------------------------------------------------------------------------------
-- Description: Flow restriction - variable area
-------------------------------------------------------------------------------
-- Revisions  :
-- Date        Version     Author              Description
-- 2001-06-16  1.0         Mentor Graphics     Created
-- 2002-05-28  1.1         Mentor Graphics     Updated std format
-- 2002-07-24  1.2         Mentor Graphics     Fixed bug on opening calc.
-------------------------------------------------------------------------------
--
-- ...Model Summary
--
-- The Valve, or Variable Flow Restriction models the characteristics
-- of a sharp-edged orifice in terms of flow rate as a function of
-- pressure drop across the device. This model captures the additional
-- effect of having the area be variable as a TRANSLATIONAL attachment
-- that can be connected to other mechanical system models. Both the
-- laminar and turbulent flow regions are accounted for using textbook
-- equations for an ideal orifice. The relative pressure drop from port1
-- to port2 is used to calculate the flow rate. The relative position of
-- the attach1 is used to calculate instantaneous area. The polarity of
-- the flow rate is consistant with the general convention where the value
-- is positive when the "flow" is from port1 through to port2.
--
-- ...Netlist Example
--
-- This netlist example illustrates a typical application where the
-- variable orifice is used to model a restriction between FLUIDIC nodes,
-- controlled in part by the position of the TRANSLATIONAL node.
--
-- Valve_01: entity work.valve (internal)
--              generic map ( pos_open => 1.0e-3,
--                            pos_close => 0.0,
--                            area_max => 1.0e-6,
--                            area_min => 1.0e-9,                           
--                            cd_turb => 0.62,
--                            viscosity => 15.0e-3,
--                            density=> 850.0,
--                            re_lam2turb => 10.0
--                             )
--              port map (port1=> pr_upstream, port2 => fluidic_ref,
--                          attach1 => pos_spool);
-------------------------------------------------------------------------------

library IEEE;
use IEEE.MATH_REAL.all;
use IEEE.fluidic_systems.all;
use IEEE.mechanical_systems.all;

entity valve is
  generic (
    pos_open              : displacement;          -- Translational position for fully open (m)
    pos_close             : displacement := 0.0;   -- Translational position for fully closed (m)
    area_max              : real;                  -- Maximum area of opening (m**2)
    cd_turb               : real := 0.62;          -- Value of Cd for turbulent region
    visc                  : viscosity := 15.0e-3;  -- Fluid absolute viscosity (N*sec/m**2)
    dens                  : density := 850.0;      -- Fluid density (kg/m**3)
    area_min              : real := 1.0e-12;       -- Minimum area of opening (m**2)
    re_lam2turb           : real := 10.0);         -- Reynolds Number for laminar to turbulent transition
  
  port (
    terminal port1, port2 : fluidic;
    terminal attach1      : translational);

end entity valve; 

--  ...Model Characteristics
--
--  The turbulent flow rate from port1 to port2 (THROUGH) is calculated using
--  the following equation:
--
--  flow(turbulent) = cd_turb * area * SQRT(2 * DeltaP / dens)
--      where
--      cd_turb = cofficient of discharge for turbulent flow
--      area = cross-sectional area
--      DeltaP  = differential pressure (port1 - port2)
--      dens = fluid density
--
--  Note that if the pressure differential, DeltaP, is negative,
--  the flow rate will also be negative. The negative DeltaP
--  must be made positive for the purpose of taking the SQRT()
--  but the flow polarity will reflect correctly the direction
--  of flow.
--
--  The area is calculated in the model based on the CONSTANTS
--  pos_open, pos_close, area_max, area_min, and the position
--  of the attach1 pin as follows:
--
--  If pos_open > pos_close
--  If position of attach1 <= pos_close then area = area_min
--  If position of attach1 >= pos_open then area = area_max
--  If in between then area is linear interpolation between
--  pos_close and pos_open and area_min and area_max
--
--  If pos_open < pos_close
--  If position of attach1 <= pos_open then area = area_max
--  If position of attach1 >= pos_close then area = area_min
--  If in between then area is linear interpolation between
--  pos_close and pos_open and area_min and area_max
--
--  For low values of differential pressure and corresponding low flow rates, 
--  the flow is laminar and therefore directly proportional to pressure. The
--  Reynolds number is the indicator for turbulent vs. laminar flow conditions:
--
--      Reynolds = (dens * dia_hyd * flow) / (visc * area)
--        where
--        area  == math_pi * dia_spool_eff * opening
--        dia_hyd == 4.0 * area / perimeter
--            and where
--            perimeter = 2.0 * (math_pi * dia_spool_eff + opening)
--            opening = effective opening displacement of the valve
--
--  The GENERIC re_lam2turb defines the Reynolds Number where the flow transitions
--  between laminar and turbulent. If the Reynolds number is less then the specified 
--  re_lam2turb, then the flow is laminar and the flow rate is given by:
--
--        flow(laminar) = deltaP * (2.0 * area * dia_hyd * cd_turb**2) / (re_lam2turb * visc)
--
--  The pressure value deltaP_lam2turb is used in the model to determine which flow
--  equation to use. It is computed by:
--
--        deltaP_lam2turb = (visc * re_lam2turb)**2 / (2.0 * dens * (cd_turb**2) * (dia_hyd**2))
--  
--  At the pressure deltaP_lam2turb, the laminar and turbulent flow equations have the 
--  same value (continuous transition), but the slope (flow vs. pressure) changes
--  discontinuously. For that reason, a break statement is used at both the positive and negative 
--  flow transition points.

architecture basic of valve is

  constant dia_spool_eff : displacement := (area_max-area_min) /
                                           (math_pi*abs(pos_open-pos_close));
  constant open_min      : displacement := area_min/(math_pi * dia_spool_eff);

  quantity deltaP across flow through port1 to port2;
  quantity position across attach1 to translational_ref;

  quantity area            : real;
  quantity dia_hyd         : displacement;
  quantity perimeter       : displacement;
  quantity opening         : displacement;
  quantity deltaP_lam2turb : pressure;
  
begin

  -- Determine Opening
  if (pos_open > pos_close) use
    if position'above(pos_open) use
      opening == pos_open - pos_close + open_min;
    elsif position'above(pos_close) use
      opening   == position - pos_close +open_min;
    else
      opening   == open_min;
    end use;
  else
    if position'above(pos_close) use
      opening == open_min;
    elsif position'above(pos_open) use
	  opening   == pos_close - position + open_min;
    else
      opening   == pos_close - pos_open + open_min;
    end use;
  end use;

  -- BREAK because of opening vs. position slope discontinuity at pos_open, pos_close.
  break on position'above(pos_close), position'above(pos_open);

  -- Determine Flow-Area Geometry
  perimeter == 2.0 * (math_pi * dia_spool_eff + opening);
  area  == math_pi * dia_spool_eff * opening;
  perimeter * dia_hyd == 4.0 * area;
  deltaP_lam2turb * (dia_hyd**2) == (visc**2)*(re_lam2turb**2)/(2.0*dens*(cd_turb**2));

  -- Determine Flow Rate
  if deltaP > deltaP_lam2turb use           --Positive Turbulent Flow
    flow == cd_turb*area*sqrt(2.0*abs(deltaP)/dens);
  elsif deltaP >= -deltaP_lam2turb use       --Laminar Flow
    flow == deltaP*(2.0*area*dia_hyd*cd_turb**2)/(re_lam2turb * visc);
  else                                      --Negative Turbulent Flow
    flow == -1.0*cd_turb*area*sqrt(2.0*abs(deltaP)/dens);
  end use;

  -- BREAK because of flow vs. pressure slope discontinuity at transition.
  break on deltaP'above(deltaP_lam2turb), deltaP'above(-deltaP_lam2turb);

end architecture basic;
-------------------------------------------------------------------------------
-- Copyright (c) 2001 Mentor Graphics Corporation
-------------------------------------------------------------------------------