%File: ~/OOP/element/BeamWithHinges2D.tex
%What: "@(#) BeamWithHinges2D.tex, revA"

NEED TO ADD ADD\_INERTIA\_LOAD TO INTERFACE .. SEE EARTHQUAKE\_PATTERN
CLASS.\\

\noindent {\bf Files}   \\
\indent \#include $<\tilde{ }$/element/BeamWithHinges2D.h$>$  \\

\noindent {\bf Class Declaration}  \\
\indent class BeamWithHinges2D: public DomainComponent \\

\noindent {\bf Class Hierarchy} \\
\indent TaggedObject \\
\indent MovableObject \\
\indent\indent DomainComponent \\
\indent\indent\indent Element \\
\indent\indent\indent\indent {\bf BeamWithHinges2D} \\

\noindent {\bf Description}  \\
\indent BeamWithHinges2D is a beam-column element which uses the force
based formulation for its state determination.  This element has
material non-linear hinges at both ends and exhibits linear elastic
behavior through its interior region, including linear elastic shear
effects. \\

\noindent {\bf Class Interface} \\
\indent // Constructors \\
\indent {\em BeamWithHinges2D (int tag, int nodeI, int nodeJ, double
E, double I, double A, double G, double alpha,
SectionForceDeformation \&sectionI, double ratioI,
SectionForceDeformation \&sectionJ, double ratioJ,
const Vector \&distrLoad, double massDens = 0);}  \\
\indent {\em BeamWithHinges2D (int tag, int nodeI, int nodeJ, double
E, double I, double A, double G, double alpha,
SectionForceDeformation \&sectionI, double ratioI,
SectionForceDeformation \&sectionJ, double ratioJ,
double massDens = 0);}  \\
\indent {\em BeamWithHinges2D ();} \\ \\
\indent // Destructor \\
\indent {\em ~ $\tilde{}$BeamWithHinges2D ();}\\ \\
\indent // Public Methods dealing with Nodes and dof\\
\indent {\em int getNumExternalNodes(void) const;} \\
\indent {\em const ID \&getExternalNodes(void);} \\
\indent {\em int getNumDOF(void);}\\ \\
\indent // Public Methods dealing with State\\
\indent{\em int commitState(void);} \\
\indent{\em int revertToLastCommit(void);} \\ 
\indent{\em int revertToStart(void);} \\ \\
\indent // Public Methods for obtaining Linearized Stiffness,
Mass and Damping Matrices\\
\indent {\em const Matrix \&getTangentStiff(void);} \\
\indent {\em const Matrix \&getSecantStiff(void);} \\
\indent {\em const Matrix \&getDamp(void);} \\
\indent {\em const Matrix \&getMass(void);} \\ \\
\indent // Public Methods for obtaining Resisting Forces \\
\indent {\em void zeroLoad(void);	}\\
\indent {\em const Vector \&getResistingForce(void);} \\
\indent {\em const Vector \&getResistingForceIncInertia(void);} \\ \\

\noindent {\bf Constructors}  \\
\indent {\em BeamWithHinges2D (int tag, int nodeI, int nodeJ, double
E, double I, double A, double G, double alpha,
SectionForceDeformation \&sectionI, double ratioI,
SectionForceDeformation \&sectionJ, double ratioJ,
const Vector \&distrLoad, double massDens);}  \\
Constructs a BeamWithHinges2D object with tag {\em tag}, unique among all elements
in the domain.  The end nodes of the element are set to be those with tags 
{\em nodeI} and {\em nodeJ}.  The elastic properties of the interior beam region
are set to be {\em E}, the modulus of elasticity; {\em I}, the second moment of
area of the beam cross-section; {\em A}, the beam cross-sectional area; {\em G},
the shear modulus; and {\em alpha}, the cross-section shape factor for elastic shear 
effects.  Element hinges are created by obtaining copies of {\em sectionI} and {\em sectionJ}.
The hinge lengths are specified as ratios of the total element length, {\em ratioI}
and {\em ratioJ}.  The element distributed load (reference value) is set to be {\em distrLoad},
and the element mass density per unit length is {\em massDens}. \\

\indent {\em BeamWithHinges2D (int tag, int nodeI, int nodeJ, double
E, double I, double A, double G, double alpha,
SectionForceDeformation \&sectionI, double ratioI,
SectionForceDeformation \&sectionJ, double ratioJ,
double massDens);}  \\
Constructs a BeamWithHinges2D object with tag {\em tag}, unique among all elements
in the domain.  The end nodes of the element are set to be those with tags 
{\em nodeI} and {\em nodeJ}.  The elastic properties of the interior beam region
are set to be {\em E}, the modulus of elasticity; {\em I}, the second moment of
area of the beam cross-section; {\em A}, the beam cross-sectional area; {\em G},
the shear modulus; and {\em alpha}, the cross-section shape factor for elastic shear 
effects.  Element hinges are created by obtaining copies of {\em sectionI} and {\em sectionJ}.
The hinge lengths are specified as ratios of the total element length, {\em ratioI}
and {\em ratioJ}.  The element mass density per unit length is {\em massDens}. \\

\indent {\em BeamWithHinges2D ();} \\
Constructs a blank BeamWithHinges2D object. \\

\noindent {\bf Destructor} \\
\indent {\em virtual~ $\tilde{}$BeamWithHinges2D();}\\ 
Invokes the section destructors. \\

\noindent {\bf Public Methods }  \\
\indent {\em int getNumExternalNodes(void) const;} \\
Returns 2, the number of external nodes for this element. \\

\indent {\em const ID \&getExternalNodes(void);} \\
Returns an ID containing the tags of the two external nodes for this element. \\

\indent {\em int getNumDOF(void);}\\
Returns 6, the number of degrees of freedom for this element. \\ 

{\em int commitState(void);} \\
Invokes {\em commitState()} on each section and returns the sum of the result of
these invocations. \\

{\em int revertToLastCommit(void);} \\
Invokes {\em revertToLastCommit()} on each section and returns the sum of the result of
these invocations. \\

{\em int revertToStart(void);} \\
Invokes {\em revertToStart()} on each section and returns the sum of the result of
these invocations. \\

{\em const Matrix \&getTangentStiff(void);} \\
Computes the element flexibility matrix, then returns its inverse, the element
stiffness matrix. The element flexibility is the sum of the hinge flexibilities,
$\mathbf{f}_I$ and $\mathbf{f}_J$, and the elastic flexibility of the beam interior,
$\mathbf{f}_{mid}$.

\begin{equation}
\label{eq:fele}
\fbas := \int_{0}^{L}{\bint^T \fsec \bint \: dx} = \mathbf{f}_I + \mathbf{f}_{mid} + \mathbf{f}_J
\end{equation}

The flexibility of the beam interior is obtained in closed form,

\begin{equation}
\mathbf{f}_{mid} = \int_{l_I}^{L-l_J}{\bint^T \fsec_{mid} \bint \: dx}
\end{equation}

where $\bint$ is the force interpolation matrix,

\begin{equation}
\bint := \left[
   \begin{array}{c c c}
      1 &           0 &               0 \\
      0 & \frac{x}{L} & \frac{x}{L} - 1 \\
      0 & \frac{1}{L} &     \frac{1}{L}
   \end{array} 
 \right]
\end{equation}

and $\fsec$ is the elastic section flexibility of the beam interior.

\begin{equation}
\fsec_{mid} = \left[
   \begin{array}{c c c}
      \frac{1}{EA} &            0 &                   0 \\
                 0 & \frac{1}{EI} &                   0 \\
                 0 &            0 & \frac{1}{\alpha GA}
   \end{array}
 \right]
\end{equation}

The hinge flexibilities, $\mathbf{f}_I$ and $\mathbf{f}_J$, are obtained
by the midpoint integration rule,

\begin{equation}
{\mathbf{f}}_i = \bint(x_i)^T \fsec_i \bint(x_i) * l_i, \:\: i=I,J
\end{equation}

where $x_i$ is the midpoint of hinge $i$, measured along the length of the
beam, and is the point at which the force interpolation matrix, $\bint$
is evaluated.  The flexiblity, $\fsec_i$, is obtained from the
constitutive relation for section $i$. \\

The element stiffness is then obtained by inversion of the element flexibility,
given by Equation \ref{eq:fele}.

\begin{equation}
\label{eq:kele}
\kbas = \fbas^{-1}
\end{equation}

The element then obtains the matrix, $\mathbf{A}$, which transforms the element basic
stiffness from its corotating frame to the global frame of reference.  The transformed
stiffness matrix, $\kele$, is then assembled into the structural system of equations.

\begin{equation}
\kele = \mathbf{A}^T \kbas \mathbf{A}
\end{equation} \\

{\em const Matrix \&getSecantStiff(void);} \\
To return the elements secant stiffness matrix. THIS SECANT MAY
BE REMOVED. \\

{\em const Matrix \&getDamp(void);} \\
To return the damping matrix. \\ 

{\em const Matrix \&getMass(void);} \\
Returns the element lumped mass matrix, $\mele$. It is assumed that the mass density per unit
length, $\rho$, is constant along the entire element, including the hinge regions.

\begin{equation}
\label{eq:mele}
\mele = \left[
   \begin{array}{c c c c c c}
      \frac{\rho L}{2} & 0 & 0 & 0 & 0 & 0 \\
      0 & \frac{\rho L}{2} & 0 & 0 & 0 & 0 \\
      0 & 0 & 0 & 0 & 0 & 0 \\
      0 & 0 & 0 & \frac{\rho L}{2} & 0 & 0 \\
      0 & 0 & 0 & 0 & \frac{\rho L}{2} & 0 \\
      0 & 0 & 0 & 0 & 0 & 0
   \end{array}
 \right]
\end{equation}

{\em void zeroLoad(void);}\\
This is a method invoked to zero the element load contributions to the residual. \\ 

{\em const Vector \&getResistingForce(void);} \\
Returns the element resisting force vector.  The basic element force vector is obtained as
the product of the basic element stiffness, $\kbas$, given by Equation \ref{eq:kele}, and the
basic element deformations, $\vbas$.

\begin{equation}
\qbas = \kbas \vbas
\end{equation}

The basic element force vector is then transformed from the corotating frame to the global frame
of reference.  The transformed force vector is then assembled into the structural system
of equations.

\begin{equation}
\label{eq:qele}
\qele = \mathbf{A}^T \qbas
\end{equation} \\

{\em const Vector \&getResistingForceIncInertia(void);} \\
Returns the element resisting force vector, $\tilde{\qele}$ with inertia forces included,

\begin{equation}
\tilde{\qele} = \qele - \mele \ddot{\mathbf u}
\end{equation}

where $\qele$ and $\mele$ are obtained from Equations \ref{eq:qele} and \ref{eq:mele}, respectively,
and $\ddot{\mathbf u}$ is the vector of trial nodal accelerations for the element. \\