///////////////////////////////////////////////////////////////////////////////
// For information as to what this class does, see the Javadoc, below.       //
// Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,       //
// 2007, 2008, 2009, 2010, 2014, 2015 by Peter Spirtes, Richard Scheines, Joseph   //
// Ramsey, and Clark Glymour.                                                //
//                                                                           //
// This program is free software; you can redistribute it and/or modify      //
// it under the terms of the GNU General Public License as published by      //
// the Free Software Foundation; either version 2 of the License, or         //
// (at your option) any later version.                                       //
//                                                                           //
// This program is distributed in the hope that it will be useful,           //
// but WITHOUT ANY WARRANTY; without even the implied warranty of            //
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the             //
// GNU General Public License for more details.                              //
//                                                                           //
// You should have received a copy of the GNU General Public License         //
// along with this program; if not, write to the Free Software               //
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA //
///////////////////////////////////////////////////////////////////////////////

package edu.cmu.tetrad.sem;

import edu.cmu.tetrad.graph.GraphNode;
import edu.cmu.tetrad.graph.Node;
import edu.cmu.tetrad.util.NamingProtocol;
import edu.cmu.tetrad.util.TetradSerializable;
import edu.cmu.tetrad.util.dist.Distribution;
import edu.cmu.tetrad.util.dist.Normal;

import java.io.IOException;
import java.io.ObjectInputStream;

/**
 * Stores information about the identity of a SEM parameter--its name, its type
 * (COEF, COVAR), and the node(s) it is associated with.
 *
 * @author Don Crimbchin (djc2@andrew.cmu.edu)
 * @author Joseph Ramsey
 */
public final class Parameter implements TetradSerializable {
    static final long serialVersionUID = 23L;

    /**
     * The default distribution from which initial values are drawn for this
     * distribution.
     */
    private static Distribution DEFAULT_DISTRIBUTION =
            new Normal(0.0, 1.0);

    /**
     * One of the anchor endpoints specifying the parameter this is.
     *
     * @serial Cannot be null.
     */
    private final Node nodeA;

    /**
     * One of the anchor endpoints specifying the parameter this is.
     *
     * @serial Cannot be null.
     */
    private final Node nodeB;

    /**
     * The name of the parameter.
     *
     * @serial Cannot be null.
     */
    private String name;

    /**
     * The type of parameter--coefficient, covariance, or variance.
     *
     * @serial Cannot be null. Should be ParamType.VAR if nodeA != nodeB and
     * ParamType.COVAR if nodeA == nodeB.
     */
    private ParamType type;

    /**
     * True iff this parameter is fixed in estimation.
     *
     * @serial Any value.
     */
    private boolean fixed = false;

    /**
     * True iff this parameter should be initialized randomly.
     *
     * @serial Any value.
     */
    private boolean initializedRandomly = true;

    /**
     * If this parameter is initialized randomly, the initial value is drawn
     * from this distribution.
     *
     * @serial Cannot be null.
     */
    private Distribution distribution = DEFAULT_DISTRIBUTION;

    /**
     * If this parameter is either fixed or not initialized randomly, returns
     * its starting value.
     *
     * @serial Any value.
     */
    private double startingValue = +1.0d;

    //================================CONSTRUCTORS=======================//

    /**
     * @param name  The name of the parameter.
     * @param type  The type of the parameter--ParamType.COEF, ParamType.VAR, or
     *              ParamType.COVAR.
     * @param nodeA The "from" node.
     * @param nodeB The "to" node. (For variance freeParameters, this must be the
     *              same as the "from" node. For covariance freeParameters, it must
     *              be different from the "from" node.)
     */
    public Parameter(String name, ParamType type, Node nodeA, Node nodeB) {
        if (name == null) {
            throw new NullPointerException("Name must not be null.");
        }
        if (type == null) {
            throw new NullPointerException("ParamType must not be null.");
        }
        if (nodeA == null) {
            throw new NullPointerException("Node A must not be null.");
        }
        if (nodeB == null) {
            throw new NullPointerException("Node B must not be null.");
        }

        if (type == ParamType.VAR && nodeA != nodeB) {
            throw new IllegalArgumentException(
                    "Variance parameters must have " +
                            "nodeA and nodeB the same.");
        }

        if (type == ParamType.COVAR && nodeA == nodeB) {
            throw new IllegalArgumentException(
                    "Covariance parameters must have " +
                            "nodeA and nodeB different.");
        }

        this.name = name;
        this.type = type;
        this.nodeA = nodeA;
        this.nodeB = nodeB;
    }

    /**
     * Generates a simple exemplar of this class to test serialization.
     */
    public static Parameter serializableInstance() {
        return new Parameter("X", ParamType.COEF, new GraphNode("X"),
                new GraphNode("Y"));
    }

    //================================PUBLIC METHODS===================//

    /**
     * @return the name of the parameter.
     */
    public String getName() {
        return name;
    }

    /**
     * Sets the name for this parameter.
     *
     * @throws IllegalArgumentException if the name does not begin with a
     *                                  letter.
     */
    public void setName(String name) {
        if (name == null) {
            throw new NullPointerException();
        }

        if (!NamingProtocol.isLegalName(name)) {
            throw new IllegalArgumentException(
                    NamingProtocol.getProtocolDescription());
        }

        this.name = name;
    }

    /**
     * @return a string representation for this parameter.
     */
    public String toString() {
        return "<" + this.name + ", " + this.type + ", " + this.nodeA + ", " +
                this.nodeB + ", " + (this.fixed ? "fixed" : "free") + ">";
    }

    /**
     * @return the "from" node for the edge this parameter is associated with.
     */
    public Node getNodeA() {
        return nodeA;
    }

    /**
     * @return the "to" node for the edge this parameter is associated with.
     */
    public Node getNodeB() {
        return nodeB;
    }

    /**
     * @return the type of this parameter--ParamType.COEF or ParamType.COVAR.
     * This is set at construction time.
     */
    public ParamType getType() {
        return type;
    }

    /**
     * @return the distributions that initial values should be drawn from for
     * this parameter.
     */
    public Distribution getDistribution() {
        return distribution;
    }

    /**
     * Sets the distribution that initial values should be drawn from for this
     * parameter. To set the parameter to always use the same initial value,
     * use tetrad.util.SingleValue.
     *
     * @see edu.cmu.tetrad.util.dist.SingleValue
     */
    public void setDistribution(Distribution distribution) {
        if (distribution == null) {
            throw new NullPointerException("Distribution must not be null.");
        }
        this.distribution = distribution;
    }

    /**
     * @return true iff this parameter should be held fixed during estimation.
     */
    public boolean isFixed() {
        return fixed;
    }

    /**
     * Sets whether this parameter should be held fixed during estimation.
     *
     * @param fixed True if the parameter will be held fixed, false if not.
     */
    public void setFixed(boolean fixed) {
        this.fixed = fixed;
    }

    /**
     * @return the starting value if this is a fixed parameter.
     */
    public double getStartingValue() {
        return startingValue;
    }

    /**
     * Sets the starting value in case this is a fixed parameter.
     */
    public void setStartingValue(double startingValue) {
        this.startingValue = startingValue;
    }

    /**
     * @return true iff this parameter should be initialized randomly by drawing
     * an initial value from its preset random distribution.
     */
    public boolean isInitializedRandomly() {
        return initializedRandomly;
    }

    /**
     * Set to true iff this parameter should be initialized randomly by drawing
     * an initial value from its preset random distribution.
     */
    public void setInitializedRandomly(boolean initializedRandomly) {
        this.initializedRandomly = initializedRandomly;
    }

    /**
     * Adds semantic checks to the default deserialization method. This method
     * must have the standard signature for a readObject method, and the body of
     * the method must begin with "s.defaultReadObject();". Other than that, any
     * semantic checks can be specified and do not need to stay the same from
     * version to version. A readObject method of this form may be added to any
     * class, even if Tetrad sessions were previously saved out using a version
     * of the class that didn't include it. (That's what the
     * "s.defaultReadObject();" is for. See J. Bloch, Effective Java, for help.
     *
     * @throws java.io.IOException
     * @throws ClassNotFoundException
     */
    private void readObject(ObjectInputStream s)
            throws IOException, ClassNotFoundException {
        s.defaultReadObject();

        if (name == null) {
            throw new NullPointerException();
        }

        if (type == null) {
            throw new NullPointerException();
        }

        if (distribution == null) {
            throw new NullPointerException();
        }

        if (type == ParamType.VAR && nodeA != nodeB) {
            throw new IllegalStateException();
        }

        if (type == ParamType.COVAR && nodeA == nodeB) {
            throw new IllegalStateException();
        }
    }
}





