% $Id$
%

\label{Explorer}

The NUOPC Component Explorer is a run-time tool that can be used to gain insight into a NUOPC Layer compliant component, or to test a component's compliance. The Component Explorer is currently available as a separate download from the prototype repository:

\begin{verbatim}
https://github.com/esmf-org/nuopc-app-prototypes/tree/develop/AtmOcnProto
\end{verbatim}

There are two parts to the Component Explorer. First the script {\tt nuopcExplorerScript} is used to compile and link the explorer application specifically against a specified component. This part of the explorer leverages and tests the standardized component dependencies discussed in section \ref{componentDep}. This step is initiated by calling the explorer script with the component's mk-file as an argument:

\begin{verbatim}
./nuopcExplorerScript <component-mk-file>
\end{verbatim}

Any issues found during this step are reported. The successful completion of this step will produce an executable called {\tt nuopcExplorerApp}. Success is indicated by 

\begin{verbatim}
SUCCESS: nuopcExplorerApp successfully built
...exiting nuopcExplorerScript.
\end{verbatim}

and failure by

\begin{verbatim}
FAILURE: nuopcExplorerApp failed to build
...exiting nuopcExplorerScript.
\end{verbatim}

The second part of the Component Explorer is the explorer application itself. It can either be built using the explorer script as outlined above (recommended when a makefile fragment for the component is available) or by using the makefile directly:

\begin{verbatim}
make nuopcExplorerApp
\end{verbatim}

In the second case the resulting {\tt nuopcExplorerApp} is not tied to a specific component, instead the executable expects a component in form of a shared object to be specified as a command line argument when executing {\tt nuopcExplorerApp}. In either case the explorer application needs to be started according to the execution requirements of the component it attempts to explore. This may mean that input files must be present, and that the executable be launched on a sufficient number of processes. In terms of the common {\tt mpirun} tool, launching of {\tt nuopcExplorerApp} may look like this
\begin{verbatim}
mpirun -np X ./nuopcExplorerApp
\end{verbatim}
for an executable that was built against a specific component. Or like this
\begin{verbatim}
mpirun -np X ./nuopcExplorerApp <component-shared-object-file>
\end{verbatim}
for an executable that expects a the component in form of a shared object. 

The {\tt nuopcExplorerApp} expects to find a configuration file by the name of {\tt explorer.config} in the run directory. The configuration file contains several basic model parameter used to explore the component. An example configuration file is shown here:

\begin{verbatim}
### NUOPC Component Explorer configuration file ###

start_year:               2009
start_month:              12
start_day:                01
start_hour:               00
start_minute:             0
start_second:             0

stop_year:                2009
stop_month:               12
stop_day:                 03
stop_hour:                00
stop_minute:              0
stop_second:              0

step_seconds:             21600

filter_initialize_phases: no

enable_run:               yes
enable_finalize:          yes
\end{verbatim}

The {\tt nuopcExplorerApp} starts to interact with the specified component, using the information read in from the configuration file. During the interaction the finding are reported to stdout, with output that will look similar to this:

\begin{verbatim}
 NUOPC Component Explorer App
 ----------------------------
 Exploring a component with a Fortran module front...
 Model component # 1 InitializePhaseMap:
   IPDv00p1=1
   IPDv00p2=2
   IPDv00p3=3
   IPDv00p4=4
 Model component # 1 // name = ocnA
   ocnA: <LongName>    : Attribute is present but NOT set!
   ocnA: <ShortName>   : Attribute is present but NOT set!
   ocnA: <Description> : Attribute is present but NOT set!
      --------
   ocnA: importState // itemCount = 2
   ocnA: importState // item # 001 // [FIELD] name = pmsl
               <StandardName> = air_pressure_at_sea_level
                      <Units> = Pa
                   <LongName> = Air Pressure at Sea Level
                  <ShortName> = pmsl
   ocnA: importState // item # 002 // [FIELD] name = rsns
               <StandardName> = surface_net_downward_shortwave_flux
                      <Units> = W m-2
                   <LongName> = Surface Net Downward Shortwave Flux
                  <ShortName> = rsns
      --------
   ocnA: exportState // itemCount = 1
   ocnA: exportState // item # 001 // [FIELD] name = sst
               <StandardName> = sea_surface_temperature
                      <Units> = K
                   <LongName> = Sea Surface Temperature
                  <ShortName> = sst
\end{verbatim}

Turning on the Compliance Checker (see section \ref{Checker}) will result in additional information in the log files.






