//******************************************************************************************************
//  Alarm.cs - Gbtc
//
//  Copyright © 2010, Grid Protection Alliance.  All Rights Reserved.
//
//  Licensed to the Grid Protection Alliance (GPA) under one or more contributor license agreements. See
//  the NOTICE file distributed with this work for additional information regarding copyright ownership.
//  The GPA licenses this file to you under the Eclipse Public License -v 1.0 (the "License"); you may
//  not use this file except in compliance with the License. You may obtain a copy of the License at:
//
//      http://www.opensource.org/licenses/eclipse-1.0.php
//
//  Unless agreed to in writing, the subject software distributed under the License is distributed on an
//  "AS-IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. Refer to the
//  License for the specific language governing permissions and limitations.
//
//  Code Modification History:
//  ----------------------------------------------------------------------------------------------------
//  01/31/2012 - Stephen C. Wills
//       Generated original version of source code.
//  02/10/2012 - Stephen C. Wills
//       Moved to TimeSeriesFramework project.
//
//******************************************************************************************************

using System;

namespace GSF.TimeSeries
{
    #region [ Enumerations ]

    /// <summary>
    /// Represents the two states that an alarm can be in: raised or cleared.
    /// </summary>
    public enum AlarmState
    {
        /// <summary>
        /// Indicates that an alarm is cleared.
        /// </summary>
        Cleared = 0,

        /// <summary>
        /// Indicates that an alarm has been raised.
        /// </summary>
        Raised = 1
    }

    /// <summary>
    /// Represents the severity of alarms.
    /// </summary>
    public enum AlarmSeverity
    {
        /// <summary>
        /// Indicates that an alarm is of no importance.
        /// </summary>
        None = 0,

        /// <summary>
        /// Indicates that an alarm is informative, but not dangerous.
        /// </summary>
        Information = 50,

        /// <summary>
        /// Indicates that an alarm is not very important.
        /// </summary>
        Low = 150,

        /// <summary>
        /// Indicates that an alarm is somewhat important.
        /// </summary>
        MediumLow = 300,

        /// <summary>
        /// Indicates that an alarm is moderately importance.
        /// </summary>
        Medium = 500,

        /// <summary>
        /// Indicates that an alarm is important.
        /// </summary>
        MediumHigh = 700,

        /// <summary>
        /// Indicates that an alarm is very important.
        /// </summary>
        High = 850,

        /// <summary>
        /// Indicates than an alarm signifies a dangerous situation.
        /// </summary>
        Critical = 950,

        /// <summary>
        /// Indicates that an alarm reports bad data.
        /// </summary>
        Error = 1000
    }

    /// <summary>
    /// Represents the operation to be performed
    /// when testing values from an incoming signal.
    /// </summary>
    public enum AlarmOperation
    {
        /// <summary>
        /// Internal range test
        /// </summary>
        Equal = 1,

        /// <summary>
        /// External range test
        /// </summary>
        NotEqual = 2,

        /// <summary>
        /// Upper bound
        /// </summary>
        GreaterOrEqual = 11,

        /// <summary>
        /// Lower bound
        /// </summary>
        LessOrEqual = 21,

        /// <summary>
        /// Upper limit
        /// </summary>
        GreaterThan = 12,

        /// <summary>
        /// Lower limit
        /// </summary>
        LessThan = 22,

        /// <summary>
        /// Latched value
        /// </summary>
        Flatline = 3
    }

    #endregion

    /// <summary>
    /// Represents an alarm that tests the values of
    /// an incoming signal to determine the state of alarm.
    /// </summary>
    public class Alarm
    {
        #region [ Members ]

        // Fields
        private Ticks m_lastNegative;

        private double m_lastValue;
        private Ticks m_lastChanged;

        #endregion

        #region [ Constructors ]

        /// <summary>
        /// Creates a new instance of the <see cref="Alarm"/> class.
        /// </summary>
        public Alarm()
        {
            State = 0;
        }

        #endregion

        #region [ Properties ]

        /// <summary>
        /// Gets or sets the identification number of the alarm.
        /// </summary>
        public int ID
        {
            get;
            set;
        }

        /// <summary>
        /// Gets or sets the tag name of the alarm.
        /// </summary>
        public string TagName
        {
            get;
            set;
        }

        /// <summary>
        /// Gets or sets the identification number of the
        /// signal whose value is monitored by the alarm.
        /// </summary>
        public Guid SignalID
        {
            get;
            set;
        }

        /// <summary>
        /// Gets or sets the identification number of
        /// the measurements generated for alarm events.
        /// </summary>
        public Guid? AssociatedMeasurementID
        {
            get;
            set;
        }

        /// <summary>
        /// Gets or sets the description of the alarm.
        /// </summary>
        public string Description
        {
            get;
            set;
        }

        /// <summary>
        /// Gets or sets the severity of the alarm.
        /// </summary>
        public AlarmSeverity Severity
        {
            get;
            set;
        }

        /// <summary>
        /// Gets or sets the operation to be performed
        /// when testing values from the incoming signal.
        /// </summary>
        public AlarmOperation Operation
        {
            get;
            set;
        }

        /// <summary>
        /// Gets or sets the value to be compared against
        /// the signal to determine whether to raise the
        /// alarm. This value is irrelevant for the
        /// <see cref="AlarmOperation.Flatline"/> operation.
        /// </summary>
        public double? SetPoint
        {
            get;
            set;
        }

        /// <summary>
        /// Gets or sets a tolerance window around the
        /// <see cref="SetPoint"/> to use when comparing
        /// against the value of the signal. This value
        /// is only relevant for the <see cref="AlarmOperation.Equal"/>
        /// and <see cref="AlarmOperation.NotEqual"/> operations.
        /// </summary>
        /// <remarks>
        /// <para>The equal and not equal operations are actually
        /// internal and external range tests based on the setpoint
        /// and the tolerance. The two tests are performed as follows.</para>
        /// 
        /// <list type="bullet">
        /// <item>Equal: <c>(value &gt;= SetPoint - Tolerance) &amp;&amp; (value &lt;= SetPoint + Tolerance)</c></item>
        /// <item>Not equal: <c>(value &lt; SetPoint - Tolerance) || (value &gt; SetPoint + Tolerance)</c></item>
        /// </list>
        /// </remarks>
        public double? Tolerance
        {
            get;
            set;
        }

        /// <summary>
        /// Gets or sets the amount of time that the
        /// signal must be exhibiting alarming behavior
        /// before the alarm is raised.
        /// </summary>
        public double? Delay
        {
            get;
            set;
        }

        /// <summary>
        /// Gets or sets the hysteresis used when clearing
        /// alarms. This value is only relevant in greater
        /// than (or equal) and less than (or equal) operations.
        /// </summary>
        /// <remarks>
        /// <para>The hysteresis is an offset that provides padding between
        /// the point at which the alarm is raised and the point at
        /// which the alarm is cleared. For example, in the case of the
        /// <see cref="AlarmOperation.GreaterOrEqual"/> operation:</para>
        /// 
        /// <list type="bullet">
        /// <item>Raised: <c>value &gt;= SetPoint</c></item>
        /// <item>Cleared: <c>value &lt; SetPoint - Hysteresis</c></item>
        /// </list>
        /// 
        /// <para>The direction of the offset depends on whether the
        /// operation is greater than (or equal) or less than (or equal).
        /// The hysteresis must be greater than zero.</para>
        /// </remarks>
        public double? Hysteresis
        {
            get;
            set;
        }

        /// <summary>
        /// Gets or sets the state of the alarm (raised or cleared).
        /// </summary>
        public AlarmState State
        {
            get;
            set;
        }

        /// <summary>
        /// Gets or sets the most recent measurement
        /// that caused the alarm to be raised.
        /// </summary>
        public IMeasurement Cause
        {
            get;
            set;
        }

        #endregion

        #region [ Methods ]

        /// <summary>
        /// Tests the value of the given signal to determine
        /// whether the alarm should be raised or cleared.
        /// </summary>
        /// <param name="signal">The signal whose value is to be tested.</param>
        /// <returns>true if the alarm's state changed; false otherwise</returns>
        public bool Test(IMeasurement signal)
        {
            AlarmState previousState = State;

            if (State == AlarmState.Raised && ClearsAlarm(signal))
            {
                State = AlarmState.Cleared;
            }
            else if (State == AlarmState.Cleared && RaisesAlarm(signal))
            {
                State = AlarmState.Raised;
                Cause = signal;
            }

            return State != previousState;
        }

        // Tests the given measurement to determine whether
        // its value triggers an alarm raised event.
        private bool RaisesAlarm(IMeasurement signal)
        {
            if (Operation != AlarmOperation.Flatline)
                return CheckRange(signal);

            return CheckFlatline(signal);
        }

        // Tests the given measurement to determine whether
        // its value indicates that the signal has been in
        // the alarming range for the configured delay time.
        private bool CheckRange(IMeasurement signal)
        {
            bool result = GetTestResult(signal);
            Ticks dist;

            if (!result)
            {
                // Keep track of the last time
                // the signal was in range
                m_lastNegative = signal.Timestamp;
            }
            else
            {
                // Get the amount of time since the
                // last time the value was in range
                dist = signal.Timestamp - m_lastNegative;

                // If the amount of time is larger than
                // the delay threshold, raise the alarm
                if (dist >= Ticks.FromSeconds(Delay.Value))
                    return true;
            }

            return false;
        }

        // Tests the signal to determine whether its
        // value is within the configured alarming range.
        private bool GetTestResult(IMeasurement signal)
        {
            double value = signal.Value;

            switch (Operation)
            {
                case AlarmOperation.Equal:
                    return (value <= SetPoint + Tolerance) && (value >= SetPoint - Tolerance);

                case AlarmOperation.NotEqual:
                    return (value < SetPoint - Tolerance) || (value > SetPoint + Tolerance);

                case AlarmOperation.GreaterOrEqual:
                    return value >= SetPoint;

                case AlarmOperation.LessOrEqual:
                    return value <= SetPoint;

                case AlarmOperation.GreaterThan:
                    return value > SetPoint;

                case AlarmOperation.LessThan:
                    return value < SetPoint;
            }

            return false;
        }

        // Tests the given measurement to determine whether
        // its value triggers an alarm cleared event.
        private bool ClearsAlarm(IMeasurement signal)
        {
            if (Operation != AlarmOperation.Flatline)
                return CheckRangeClear(signal);

            return !CheckFlatline(signal);
        }

        // Tests the given measurement to determine whether its value
        // indicates that the signal has left the alarming range.
        private bool CheckRangeClear(IMeasurement signal)
        {
            double value = signal.Value;

            switch (Operation)
            {
                case AlarmOperation.GreaterOrEqual:
                    return (value < SetPoint - Hysteresis);

                case AlarmOperation.LessOrEqual:
                    return (value > SetPoint + Hysteresis);

                case AlarmOperation.GreaterThan:
                    return (value <= SetPoint - Hysteresis);

                case AlarmOperation.LessThan:
                    return (value >= SetPoint + Hysteresis);

                default:
                    return !GetTestResult(signal);
            }
        }

        // Determines whether the given value has
        // flatlined over the configured delay interval.
        private bool CheckFlatline(IMeasurement signal)
        {
            long dist, diff;

            if (signal.Value != m_lastValue)
            {
                m_lastChanged = signal.Timestamp;
                m_lastValue = signal.Value;
            }

            dist = Ticks.FromSeconds(Delay.Value);
            diff = signal.Timestamp - m_lastChanged;

            return diff >= dist;
        }

        #endregion
    }
}