% $Id$
%
% Earth System Modeling Framework
% Copyright (c) 2002-2025, University Corporation for Atmospheric Research, 
% Massachusetts Institute of Technology, Geophysical Fluid Dynamics 
% Laboratory, University of Michigan, National Centers for Environmental 
% Prediction, Los Alamos National Laboratory, Argonne National Laboratory, 
% NASA Goddard Space Flight Center.
% Licensed under the University of Illinois-NCSA License.

The ESMF VM (Virtual Machine) class is a generic representation of hardware and system software resources. There is exactly one VM object per ESMF Component, providing the execution environment for the Component code. The VM class handles all resource management tasks for the Component class and provides a description of the underlying configuration of the compute resources used by a Component.

In addition to resource description and management, the VM class offers the lowest level of ESMF communication methods. The VM communication calls are very similar to MPI. Data references in VM communication calls must be provided as raw, language-specific, one-dimensional, contiguous data arrays. The similarity between VM and MPI communication calls is striking and there are many equivalent point-to-point and collective communication calls. However, unlike MPI, the VM communication calls support communication between threaded PETs in a completely transparent fashion.

Many ESMF applications do not interact with the VM class directly very much. The  resource management aspect is wrapped completely transparent into the ESMF Component concept. Often the only reason that user code queries a Component
object for the associated VM object is to inquire about resource information, such as the {\tt localPet} or the {\tt petCount}. Further, for most applications the use of higher level communication APIs, such as provided by Array and Field, are much more convenient than using the low level VM communication calls.

The basic elements of a VM are called PETs, which stands for Persistent Execution Threads. These are equivalent to OS threads with a lifetime of at least that of the associated component. All VM functionality is expressed in terms of PETs. In the simplest, and most common case, a PET is equivalent to an MPI process. However, ESMF also supports multi-threading, where multiple PETs run as Pthreads inside the same virtual address space (VAS).

The resource management functions of the VM class become visible when a component, or the driver code, creates sub-components. Section \ref{sec:AppDriverSetVM} discusses this aspect from the Superstructure 
perspective and provides links to the relevant Component examples in the documentation.

There are two parts to resource management, the parent and the child. When the parent component creates a child component, the parent VM object provides the resources on which the child is created with {\tt ESMF\_GridCompCreate()} or {\tt ESMF\_CplCompCreate()}. The optional {\tt petList} argument to these calls limits the resources that the parent gives to a specific child. The child component, may specify - during its optional 
{\tt ESMF\_<Grid/Cpl>CompSetVM()} method - how it wants to arrange the inherited resources in its own VM. After this, all standard ESMF methods of the Component, including {\tt ESMF\_<Grid/Cpl>CompSetServices()}, will execute in the child VM. Notice that the {\tt ESMF\_<Grid/Cpl>CompSetVM()} routine, although part of the child Component, must execute {\em before} the child VM has been started up. It runs in the parent VM context. The child VM is created and started up just before the user-written set services routine, specified as an argument to {\tt ESMF\_<Grid/Cpl>CompSetServices()}, is entered.
