Projects_eac3

Projects are modules for managing test vectors, their generation, saving and loading.

Projects are identified by their "project constant" (to be found in EACconstants) which is used in EACirc configuration file. Every project has to be inheritted from abstract IProject interface and provide implementation at least to methods generateTestVectors() and shortDescription(). Projects may access and use all global resources, such as global settings and various random generators (full account of globally accessible resources and their limitations can be found in framework components description).

Functionality implemented on the project layer

General functionality implemented solely on project layer includes following:

• Project constant is automatically set in general project constructor and can be accessed anytime using constant method getProjectType().
• If project-specific evaluator was allocated (this would be done in initializeProject()), it is deallocated automatically at project destruction. During its existance, it can be accessed via project's getProjectEvaluator() method.
• Basic header for test vector files with general circuit settings is automatically created in createTestVectorFilesHeadersMain() (if test vector saving is enabled).
• When saving and loading state, general attributes (type, description, loadability) are created and checked at the project layer.

Some important methods of projects are private in IProject, because they should be called via general project interface that provides functionality useful for all projects. These are mostly distinguished by the suffix -Main in their public variant. The functionality on the project layer is as follows:

• saveProjectStateMain()
  Creates project state tree with project constant, description and loadability attribute.
  Note: Beware, all projects are unloadable by default!
• loadProjectStateMain()
  Checks, if the project constant is correct and whether the project state is loadable. If loadable, calls loadProjectState().
• createTestVectorFilesHeadersMain()
  If EACirc is set to save test vectors, creates basic header in test vector files with general circuit and test set settings. Calls virtual createTestVectorFilesHeaders() for project-specific settings.
• generateAndSaveTestVectors()
  Calls generateTestVectors(), then saves the vectors (both inputs and outputs) to the test vector file (if test vector saving is enabled).

Description of virtual IProject methods

Pure virtual methods (required by every project)

• shortDescription()
  Short human-readable description of project purpose. This method must be implemented in project.
• generateTestVectors()
  The most important method for project. When called, new set of test vectors according the configuration in global settings shall be generated and saved in globally accessible resources (see framwork components). This method must be implemented in project.

Virtual methods (optional in projects)

• loadProjectConfiguration()
  Load project-specific settings from main configuration file. Root of the configuration file is handed in argument (it should neither be modified not deallocated). Project configuration should be kept in single structure and its address shall be provided in globally accessible resources as (void*) type. You should not use any random or other global resources changing the state in this method.
• initializeProject()
  Initialize project structures (allocate memory, etc.). Headers for human-readable test vector file shall be created here. You should not use any random or other global resources changing the state in this method. If project-specific evaluator is to be used, it should be allocated here (for more details, see page on evaluators, section project-specific evaluators).
  Note: This method is called regardless of recommencing/not recommencing computation.
• initializeProjectState()
  This initialization is run just once, after loading project configuration and before generating the first set of test vectors. The state created in this method should be able to be saved/load via saveProjectState()/loadProjectState().
  Note: When recommencing computation and loading project state, this method is not called at all!
• saveProjectState()
  If project maintains internal state, it shall be completely savable and recoverable (to enable computation recommencing). Framework prepares a dynamically allocated XML structure with root node project and attributes type (containing project constant), description (containing short human-readable description) and loadable (bool containing information if the state of this project is loadable). Note: Do not save or load state of globally accessible resources, as state of these is managed by the framework.
  Note2: All projects are non-loadable by default, if have these methods implemented, set the attribute loadable to 1
• loadProjectState()
  Load complete project state. Project type and loadability are checked automatically by the framework.
• createTestVectorFilesHeaders()
  Create project-specific header in test vector files. This method is called only if EACirc is saving test vector, there is no need to double-check this.

Static methods (optional in projects)

• testingConfiguration()
  Return project configuration for testing purposes in string. Although this method is not prescribed in the IProject interface (as it needs to be statis), developers are advised to implement it. If implemented, project can be easily included in all existing self-tests (for more information, see part on testing EACirc).