\section{Household Emission}
\label{subsubsec:emission_model}

The household emission model implements an approach to calculate the emission
from annual per capita consumption and the number of inhabitants at a discharge
site. The simple approach allows a clear overview over the elements of the 
\classobj{Model} class to be usually overridden and the concepts to implement
a model uning the GREAT-ER II Model framework.

{\scriptsize
\begin{verbatim}
class HouseholdEmission( Model ):
    """Implements GREAT-ER Household Emission Model."""

    # The emission model is applied always, independent of the model mode 
    # selection
    _required_parameters = [(None , None, None),
           ('DISCH', 'POP'), ('SUBST', 'DEFAULT_CONSUMPTION')
        ]

    name = 'Household Emission Model'
     
    def setup(self, segmentID):
        """Set up Household Emission Model."""

        # Derive stochastic paramaters
        st_params = self.st_params
        
        # Shortcuts
        data = self.session.data
        ID = segmentID

        # Some parameter which only have to be processed once
        self.ID = ID
        self.Pop     = float(eval_local_setting(data,
                            ('SESS_DISCH', ID, 'pop'),
                            ('DISCH', ID, 'pop')
                          )[0])
        Consumption, status = eval_local_setting( data, 
                            ('EMISSION', ID, 'consumption'),
                            ('SUBST', 'DEFAULT_CONSUMPTION', 'value')
                        )
        self.Consumption = Parameter(('SUBST', 'DEFAULT_CONSUMPTION'),
                                    Consumption,
                                    eval_local_stochastics(status, st_params), 
                                    data['STOCHASTICS']) 

    def compute( self, segment, shot_num ):
        """Compute Household Emission Model."""

        Pop         = self.Pop
        Consumption = self.Consumption.get(shot_num)

        PHIout = Pop * Consumption / 31536000.0                # [kg/s]

        return PHIout
\end{verbatim}
}

The model implementation is explained in sections below.
\newpage

\subsection{General}

{\scriptsize
\begin{verbatim}
class HouseholdEmission( Model ):
    """Implements GREAT-ER Household Emission Model."""

    # The emission model is applied always, independent of the model mode 
    # selection
    _required_parameters = [(None , None, None),
           ('DISCH', 'POP'), ('SUBST', 'DEFAULT_CONSUMPTION')
        ]

    name = 'Household Emission Model'
\end{verbatim}
}

\begin{itemize}
    \item   The class \classobj{HouseholdEmission} inherits from 
        the \classobj{Model} class. 
    \item The \varname{\_required\_parameters} lists the required parameters:
        \varname{POP} from the discharge data and the 
        \varname{DEFAULT\_CONSUMPTION} from the substance data.
        Since the emission model is used for all model modes, 
        the mode tuple is set to 
        \varvalue{(None, None, None)}, according to
        \ref{paragraph:Required_parameters}.
    \item The \varname{name} of the model is specified.
\end{itemize}

\subsection{Setup}

{\scriptsize
\begin{verbatim}
    def setup(self, segmentID):
        """Set up Household Emission Model."""

        # Shortcuts
        st_params = self.st_params
        data = self.session.data
        ID = segmentID

        # Some parameter which only have to be processed once
        self.ID = segmentID
        self.Pop = float(eval_local_setting(data,
                            ('SESS_DISCH', ID, 'pop'),
                            ('DISCH', ID, 'pop')
                          )[0])

        # Potentially distributed parameters
        Consumption, status = eval_local_setting( data, 
                            ('EMISSION', ID, 'consumption'),
                            ('SUBST', 'DEFAULT_CONSUMPTION', 'value')
                        )
        self.Consumption = Parameter(('SUBST', 'DEFAULT_CONSUMPTION'),
                                    Consumption,
                                    eval_local_stochastics(status, st_params), 
                                    data['STOCHASTICS']) 
\end{verbatim}    
}

\begin{itemize}
    \item Some shortcuts to make the code more transparent. 
        \varname{self.st\_params} and \varname{self.session} have been
        initialized on instantiation of the model object by the graph
        initialization (see \ref{sec:GraphClass}).
    \item The segment ID is available on setup and is stored for later
        referential use.
    \item The population is not considered as distributed, hence the value is
        stored directly under (\varname{self.Pop}):
        \begin{itemize}
            \item Since the default value (from the catchment data, discharge
                table) can be overwritten by a value entered in the emission
                dialogs, first evaluate if a local setting is present.
            \item According to \ref{subsubsec:eval_local_setting} 
                \method{eval\_local\_setting} returns a tuple of 
                value and a status.
                Here we need only the value, so take the value out of the
                tuple.
            \item The value is provided as a String, for later calculations we
                need a number, so cast the value to a Float.   
        \end{itemize}
    \item Evaluate a potential local setting and store consumption
        value and status.
    \item The consumption is potentially distributed, hence we have to
        instantiate a \classobj{Parameter} object:
        \begin{itemize}
            \item The (BlockID, FieldID) tuple identifies the series of Monte
                Carlo shots.
            \item \varname{Consumption} is the value 
                (or pair of descriptives) derived above.
            \item \method{eval\_local\_stochastics} checks if the 
		default consumption is overwritten by a local value. 
		In case, the function returns \varvalue{None} (see 
		\ref{subsubsec:eval_local_stochastics}), which effectively 
		switches of stochastics for this objects local consumption.
		Local values are fixed by definition.
            \item \varname{data} provides the dictionary of series of 
                Monte Carlo shots.
        \end{itemize}
\end{itemize}

\subsection{Compute}

{\scriptsize
\begin{verbatim}
    def compute( self, segment, shot_num ):
        """Compute Household Emission Model."""

        Pop         = self.Pop
        Consumption = self.Consumption.get(shot_num)

        PHIout = Pop * Consumption / 31536000.0                # [kg/s]

        return PHIout
\end{verbatim}
}

\begin{itemize}
	\item \varname{Pop} is a static value.
	\item For the consumption the value for the current Monte Carlo shot
		(identified by \varname{shot\_num}) has to be obtained from the 
		consumption parameter object.
	\item Since consumption is provided as $[kg/(capita \cdot year)]$
		a unit conversion has to be applied.
	\item The mass flux out of the segment has to be returned.
\end{itemize}

A compact version of the \method{compute} could be also:
{\scriptsize
\begin{verbatim}
    def compute( self, segment, shot_num ):
        """Compute Household Emission Model."""

        return self.Pop * self.Consumption.get(shot_num) / 31536000.0
\end{verbatim}
}
