Table of Contents
In this exercise, you will work with pre-built components from the integrator example to compose a CCA-based application and execute it. Specifically you will use a Monte Carlo integration algorithm on the function 4/(1+x^2), which gives pi as the result.
The components available are:
- Drivers:
-
drivers.CXXDriver*, drivers.F90Driver*
- Integrators:
-
integrators.MonteCarlo, integrators.Midpoint*
- Functions:
-
functions.PiFunction, functions.CubeFunction*
- Random Number Generators:
-
randomgens.RandNumGenerator (required by integrators.MonteCarlo)
Components marked with a “*” are ones that you will be creating in the subsequent exercises (you only need to do one of the two driver components), but as we have mentioned, the pre-built tree include completed examples of all of the components.
Below are three different procedures for this exercise. In Section 2.1, “A CCA Application in Detail”, you interact directly with Ccaffeine on the command line to do everything. This is the best place to start to understand how to assemble and run a CCA application. In Section 2.2, “ Running Ccaffeine Using an rc File ”, you will see how the steps you performed manually in the first procedure can be captured in a script that Ccaffeine reads. This is the more common scenario because it gives you an easy way to represent a complete CCA application that is easy to reproduce, or to adapt to other situations, without having to re-do everything from scratch every time you want to run it. This is probably the approach you'll want to use when testing your work in the subsequent exercises. Finally, in Section 2.3, “Using the GUI Front-End to Ccaffeine”, we use a graphical front-end to Ccaffeine, which allows you to perform the composition and execution of the application using a “visual programming” metaphor. This procedure will only work if you have an X11 windowing system installation on your machine.
In this section, you will interact directly with the Ccaffeine framework to assemble and run several different numerical integration applications from pre-built components.
We will present the procedure in the form of a dialog between you and the Ccaffeine framework. Things you are supposed to type are presented like this and Ccaffeine's output will be presented like this. Note that Ccaffeine's input prompt is “cca>”. Particular features of the output will sometimes be marked and discussed in further detail below the output fragment.
![[Tip]](images/tip.png) |
Tip |
|---|---|
|
The complete set of Ccaffeine commands for this procedure can be found in $CCA/src/components/examples/task0_rc. You can use this file for reference, or to cut and paste commands into Ccaffeine. |
|
-
Start the Ccaffeine framework with the command ccafe-single. ccafe-single is one of several ways to invoke the Ccaffeine framework, and is used for single-process (i.e. sequential) interactive sessions; ccafe-batch is designed for use in non-interactive situations, including parallel jobs; and ccafe-client is designed to interact with a front-end GUI rather than with a user at the command line interface.
Here is what you'll see (note that some of the output lines have been folded for presentation here, indicated by “\”):
(16251) CmdLineClientMain.cxx: MPI_Init not called in \
ccafe-single mode.
(16251) CmdLineClientMain.cxx: Try running with ccafe-single \
--ccafe-mpi yes , or
(16251) CmdLineClientMain.cxx: try setenv CCAFE_USE_MPI 1 to force MPI_Init.
(16251) my rank: -1, my pid: 16251
my rank: -1, my pid: 16251
my rank: -1, my pid: 16251
my rank: -1, my pid: 16251Type: One Processor Interactive
CCAFFEINE configured with babel.
cca>
CmdContextCCAMPI::initRC: No rc file found. Pallet may be empty.
Lines between these two markers give information about the status of MPI in the Ccaffeine framework, including the processes rank if MPI is initialized. As the messages indicate, ccafe-single is intended for single-process use and does not normally call MPI_Init, but if you're running parallel and having problems with the MPI environment, this is the first place to look for signs of trouble.
This message confirms that this Ccaffeine executable was configured and built to work with Babel. This is a useful thing to check when you're using an unfamiliar installation of Ccaffeine, or the first time you Ccaffeine after building it yourself.
It is common to use an “rc” file with Ccaffeine to help assemble and run the application. This is the place where Ccaffeine confirms that it loaded the rc file you intended (or in this case, it confirms that we didn't specify one). If there is an rc file, the Ccaffeine output from the commands it contains will follow this message, so there may be a lot more text between this message and the “cca>” prompt at which you can interact with Ccaffeine.
![[Note]](images/note.png)
Note We present Ccaffeine's output with “spew” disabled (the default). If Ccaffeine is configured and built with the --enable-spew option, you will see a lot of debugging output from Ccaffeine itself in addition to what we show here.
-
Ccaffeine uses a “path” to determine where it should look for CCA components (specifically the .cca files, which internally point to the actual libraries that are needed). When it starts up, Ccaffeine's path is empty, and it has no idea where to find components. Next you will set the path that points to the pre-built components:
path pathBegin pathEnd! empty path. cca>path set /san/shared/cca/tutorial/src/components/lib # There are allegedly 8 classes in the component path cca>path pathBegin pathElement /san/shared/cca/tutorial/src/components/lib pathEnd
Path-related commands in Ccaffeine include:
- path append
-
Adds a directory to the end of the current path.
- path init
-
Sets the path from the value of the $CCA_COMPONENT_PATH environment variable.
- path prepend
-
Adds a directory to the beginning of the current path.
- path set
-
Sets the path to the value provided.
Tip Typing help at the Ccaffeine cca> prompt will provide a complete list of the commands Ccaffeine's scripting language understands.
-
Ccaffeine also has the concept of a palette of components from which applications can be assembled. The palette command will show you what is currently in the palette, and the repository get-global class_name command is used to get the component of the specified class name from the repository (path) and load it into the palette:
cca>palette Components available: cca>repository get-global drivers.CXXDriver Loaded drivers.CXXDriver NOW GLOBAL . cca>repository get-global functions.PiFunction Loaded functions.PiFunction NOW GLOBAL . cca>repository get-global integrators.MonteCarlo Loaded integrators.MonteCarlo NOW GLOBAL . cca>repository get-global randomgens.RandNumGenerator Loaded randomgens.RandNumGenerator NOW GLOBAL . cca>palette Components available: drivers.CXXDriver functions.PiFunction integrators.MonteCarlo randomgens.RandNumGenerator
-
Next, you need to instantiate the components you're going to use. The instances command will list all the component instances in Ccaffeine's work area, or arena. The command instantiate class_name instance_name will create an instance of the specified class from the palette with the specified instance name and call the new component instance's setServices method.
cca>instances FRAMEWORK of type Ccaffeine-Support cca>instantiate drivers.CXXDriver driversCXXDriver driversCXXDriver of type drivers.CXXDriver successfully instantiated cca>instantiate functions.PiFunction functionsPiFunction functionsPiFunction of type functions.PiFunction successfully instantiated cca>instantiate integrators.MonteCarlo integratorsMonteCarlo integratorsMonteCarlo of type integrators.MonteCarlo successfully instantiated cca>instantiate randomgens.RandNumGenerator randomgensRandNumGenerator randomgensRandNumGenerator of type randomgens.RandNumGenerator successfully instantiated cca>instances FRAMEWORK of type Ccaffeine-Support driversCXXDriver of type drivers.CXXDriver functionsPiFunction of type functions.PiFunction integratorsMonteCarlo of type integrators.MonteCarlo randomgensRandNumGenerator of type randomgens.RandNumGenerator
Note When you instantiate a component, you can name it whatever you like as long as it is unique with respect to all of the components that you've instantiated in your session with the framework. It is possible to instantiate the a given component class multiple times (with different names, of course).
-
Once the components you need are instantiated, you need to connect up their ports appropriately. The display chain command will list the component instances in Ccaffeine's arena and any connections among their ports. To make a connection, you use the command connect user_instance_name user_port_name provider_instance_name provider_port_name (note that some of the input lines have been folded with “\” to fit on the page -- you'll have to rejoin them when you type in the commands because Ccaffeine doesn't understand continuation lines):
cca>display chain Component FRAMEWORK of type Ccaffeine-Support
Component driversCXXDriver of type drivers.CXXDriver
Component functionsPiFunction of type functions.PiFunction
Component integratorsMonteCarlo of type integrators.MonteCarlo
Component randomgensRandNumGenerator of type randomgens.RandNumGenerator
cca>connect driversCXXDriver IntegratorPort integratorsMonteCarlo \
IntegratorPort
driversCXXDriver))))IntegratorPort---->IntegratorPort((((integratorsMonteCarlo
connection made successfully
cca>connect integratorsMonteCarlo FunctionPort functionsPiFunction \
FunctionPort
integratorsMonteCarlo))))FunctionPort---->FunctionPort((((functionsPiFunction
connection made successfully
cca>connect integratorsMonteCarlo RandomGeneratorPort \
randomgensRandNumGenerator RandomGeneratorPort
integratorsMonteCarlo))))RandomGeneratorPort---->\
RandomGeneratorPort((((randomgensRandNumGenerator
connection made successfully
cca>display chain
Component FRAMEWORK of type Ccaffeine-Support
Component driversCXXDriver of type drivers.CXXDriver
is using IntegratorPort connected to Port: IntegratorPort provided by \
component integratorsMonteCarlo
Component functionsPiFunction of type functions.PiFunction
Component integratorsMonteCarlo of type integrators.MonteCarlo
is using FunctionPort connected to Port: FunctionPort provided by \
component functionsPiFunction
is using RandomGeneratorPort connected to Port: RandomGeneratorPort \
provided by component randomgensRandNumGenerator
Component randomgensRandNumGenerator of type randomgens.RandNumGenerator
At this point, there are no connections, so the output of display chain looks very much like that of instances -- just a simple listing of the component instances in the arena.
Characteristic of the output of a connect command is the ASCII “cartoon” illustrating the connection, with the user on the left and the provider on the right.
Now the output of display chain lists the connections associated with each component instance. Note that the connection information is printed with the using component instance only.
Note Port names and port types are defined by the person who implements the component. They have to be unique within the component, but not across an entire application. In order to connect a uses port to a provides port, the types of the port must match, but the names need not match.
Tip In the Ccaffeine framework, you can find out what ports a particular component uses and provides with the command display component instance_name:
cca>display component integratorsMonteCarlo ------------------------------------ Instance name: integratorsMonteCarlo Class name: integrators.MonteCarlo ------------------------------------ UsesPorts registered for integratorsMonteCarlo 0. Instance Name: FunctionPort Class Name: function.FunctionPort 1. Instance Name: RandomGeneratorPort Class Name: \ randomgen.RandomGeneratorPort ------------------------------------ ProvidesPorts registered for integratorsMonteCarlo Instance Name: IntegratorPort Class Name: integrator.IntegratorPort ------------------------------------
-
At this point, you have a fully-assembled application and are ready to run it!
While most CCA ports are defined by component developers, the CCA specification includes a special port named GoPort. The purpose of this port is have a way of kicking off the execution of a component. The command go instance_name go_port_name instructs the framework to invoke the specified go port:
cca>go driversCXXDriver GoPort Value = 3.141768 ##specific go command successful
and you can see a (fairly inaccurate) value for pi computed by Monte Carlo integration of the function 4/(1+x^2).
At this stage, you have successfully composed and run a CCA application based on existing components. In the remainder of this procedure, we'll see how it is possible to dynamically change the application you've assembled by disconnecting components and connecting others in their place. Or you can jump straight to Step 11 to (gracefully) end this session with Ccaffeine and move on to other procedures in this chapter, or on to other tasks altogether.
-
At the moment, Ccaffeine's palette contains only the components we needed for the first application. Now, we'll add some more components to the palette and instantiate them in the arena:
cca>repository get-global integrators.Midpoint Loaded integrators.Midpoint NOW GLOBAL . cca>instantiate integrators.Midpoint integratorsMidpoint integratorsMidpoint of type integrators.Midpoint successfully instantiated cca>repository get-global functions.CubeFunction Loaded functions.CubeFunction NOW GLOBAL . cca>instantiate functions.CubeFunction functionsCubeFunction functionsCubeFunction of type functions.CubeFunction successfully instantiated
Note There is no harm in having components you don't use in the palette, or even having instances of them in the arena.
-
In order to be able to swap out components for others, we first need to disconnect them. The disconnect command has the same syntax as the connect command, with both the uses and provides end points of the connection being specified.
Let's begin by changing the Monte Carlo integrator for another. The integrator is connected to both the driver and the function. (And also to the random number generator, but since we don't need it for anything else, there is no harm in leaving that connection intact.)
cca>disconnect driversCXXDriver IntegratorPort integratorsMonteCarlo \ IntegratorPort driversCXXDriver))))IntegratorPort-\ \-IntegratorPort((((integratorsMonteCarlo connection broken successfully
cca>disconnect integratorsMonteCarlo FunctionPort functionsPiFunction \
FunctionPort
integratorsMonteCarlo))))FunctionPort-\ \-FunctionPort((((functionsPiFunction
connection broken successfully
The disconnect command prints an ASCII cartoon of a broken connection, similar to that printed by the connect command.
-
Once we connect up a new integrator (in this case, using the mid-point rule algorithm) to the driver and function, we have a new “application” that's ready to run:
cca>connect driversCXXDriver IntegratorPort integratorsMidpoint \ IntegratorPort driversCXXDriver))))IntegratorPort---->IntegratorPort((((integratorsMidpoint connection made successfully cca>connect integratorsMidpoint FunctionPort functionsPiFunction \ FunctionPort integratorsMidpoint))))FunctionPort---->FunctionPort((((functionsPiFunction connection made successfully cca>display chain Component FRAMEWORK of type Ccaffeine-Support Component driversCXXDriver of type drivers.CXXDriver is using IntegratorPort connected to Port: IntegratorPort provided by \ component integratorsMidpoint Component functionsCubeFunction of type functions.CubeFunction
Component functionsPiFunction of type functions.PiFunction
Component integratorsMidpoint of type integrators.Midpoint
is using FunctionPort connected to Port: FunctionPort provided by \
component functionsPiFunction
Component integratorsMonteCarlo of type integrators.MonteCarlo
is using RandomGeneratorPort connected to Port: RandomGeneratorPort \
provided by component randomgensRandNumGenerator
Component randomgensRandNumGenerator of type \
randomgens.RandNumGenerator
cca>go driversCXXDriver GoPort
Value = 3.141553
##specific go command successful
Observe that there are a number of component instances in the arena that we have either never used (functionsCubeFunction) or which we have disconnected from the rest of the application (integratorsMonteCarlo and randomgensRandNumGenerator).
-
Finally, we swap the pi function for an x^3 function and run a third application built from the same set of components:
cca>disconnect integratorsMidpoint FunctionPort functionsPiFunction \ FunctionPort integratorsMidpoint))))FunctionPort-\ \-FunctionPort((((functionsPiFunction connection broken successfully cca>connect integratorsMidpoint FunctionPort functionsCube FunctionPort integratorsMidpoint))))FunctionPort---->FunctionPort((((functionsCubeFunction connection made successfully cca>display chain Component FRAMEWORK of type Ccaffeine-Support Component driversCXXDriver of type drivers.CXXDriver is using IntegratorPort connected to Port: IntegratorPort provided by \ component integratorsMidpoint Component functionsCubeFunction of type functions.CubeFunction Component functionsPiFunction of type functions.PiFunction Component integratorsMidpoint of type integrators.Midpoint is using FunctionPort connected to Port: FunctionPort provided by \ component functionsCubeFunction Component integratorsMonteCarlo of type integrators.MonteCarlo is using RandomGeneratorPort connected to Port: RandomGeneratorPort \ provided by component randomgensRandNumGenerator Component randomgensRandNumGenerator of type randomgens.RandNumGenerator cca>go driversCXXDriver GoPort Value = 0.250010 ##specific go command successful To exit Ccaffeine “politely” and allow it to cleanly shutdown and destroy all components, use the quit command:
cca>quit bye! exit