Revision as of 16:02, 2 April 2012

Changing the main Python script

Import applications using the new module

The main difference between the KratosMultiphysics module and the old import style is that applications_interface is no longer used and that the Kernel is initialized internally by the module, so it is no longer required to initialize it in the Python script. Updating your main script to use the new format should be straightforward. Consider this script using the existing applications interface format:

 ##################################################################
 ##################################################################
 ## ATTENTION: here the order is important
 
 #including kratos path
 kratos_libs_path            = fluid_only_var.kratos_path + '/libs' ##kratos_root/libs
 kratos_applications_path    = fluid_only_var.kratos_path + '/applications' ##kratos_root/applications
 kratos_benchmarking_path = fluid_only_var.kratos_path +'/benchmarking' ##kratos_root/benchmarking
 import sys
 sys.path.append(kratos_libs_path)
 sys.path.append(kratos_applications_path)
 sys.path.append(kratos_benchmarking_path)
 
 import benchmarking
 
 #importing Kratos main library
 from Kratos import *
 kernel = Kernel()   #defining kernel
 
 #importing applications
 import applications_interface
 applications_interface.Import_IncompressibleFluidApplication = True
 applications_interface.Import_ExternalSolversApplication = True
 applications_interface.ImportApplications(kernel, kratos_applications_path)
 
 ## from now on the order is not anymore crucial
 ##################################################################
 ##################################################################
 from KratosIncompressibleFluidApplication import *
 from KratosExternalSolversApplication import *

The equivalent import using the KratosMultiphysics module is

 # including path to KratosMultiphysics
 import sys
 sys.path.append(fluid_only_var.kratos_path)
 
 # importing kratos
 from KratosMultiphysics import *
 from KratosMultiphysics.IncompressibleFluidApplication import *
 from KratosMultiphysics.ExternalSolversApplication import *

The order in which the applications are imported is not important, but they should be imported before we start defining the solvers or reading the model part.

In general, the name used to import the applications is the same as the one used now to import the .so, but adding the "Multiphysics." part. For example:

 from KratosStructuralApplication import * --> from KratosMultiphysics.StructuralApplication import *
 from KratosPFEMApplication import *       --> from KratosMultiphysics.PFEMApplication import *

A note about benckmarks

The benchmarking tools are not integrated in the KratosMultiphysics module, so the import of the benchmarking module should be left as usual:

 kratos_path = '../../../../' ##kratos_root
 kratos_benchmarking_path = '../../../../benchmarking' ##kratos_root/benchmarking
 import sys
 sys.path.append(kratos_path)
 sys.path.append(kratos_benchmarking_path)
 import benchmarking

If you need mpi

An additional feature of the KratosMultiphysics module is that it provides a minimal set of instructions to use MPI from Python, which will allow us to drop the dependency on Boost's Python MPI interface. If you are using MPI, it is strongly recommended that you update your code to use the new MPI interface. To do this, replace the existing imports of mpi:

 import mpi

or

 try:
   import boost.mpi as mpi
 except ImportError:
   import mpi

with

 from KratosMultiphysics.mpi import *

This will provide an object called "mpi" that can be used to perform basic mpi operations (currently rank, size, barrier, gather, allgather). In principle, no further changes are required to use it in existing code, but note that the capabilities of this object are much more limited that the ones in boost.mpi.

Changes in Python solvers and utilities

All Python solvers and utilities provided by Kratos must be updated to use the KratosMultiphysics module. Changes required are similar to the ones in the main script, with some differences that will be outlined here.

Import applications using the new module

Currently, all Python solvers start by importing the required applications. This should remain the same, but using the KratosMultiphysics module instead of importing the libraries directly.

 #importing the Kratos Library
 from KratosMultiphysics import *
 from KratosMultiphysics.IncompressibleFluidApplication import *
 from KratosMultiphysics.MeshingApplication import *
 # Check that KratosMultiphysics was imported in the main script
 CheckForPreviousImport()

The difference here is in the use of the solver: At runtime, the solver will throw an error if the applications that it tries to import have not been imported from the main script before. So, in the previous example, you will get a runtime error if you try to import this solver without importing both IncompressibleFluidApplication and MeshingApplication in the main script.

Check that the module was also used in the main script

The final line in the import block calls a function that checks that the main script also used the KratosMultiphysics module. This is necessary to detect and prevent an error that will happen if an old main script that uses applications_interface tries to use a solver in the new format. Please add it just after the import to all Python solvers and utilities.

Optional imports in particular functions

In some cases, a solver uses an application for a particular task that is only performed in some cases. An example would be the fractional step solver, which provides a funcion to refine the mesh adaptively and requires importing the MeshingApplication for this. With the new module format, all models using the fractional step solver would require importing the meshing application in the main script, even in the cases where the refinement will not be used. To prevent this from happening, the required application can be imported only by the functions that use it, instead of at the start of the solver. Unfortunately, the use of from --- import * inside functions is discouraged in Python (and will potentially produce errors in future Python versions), so a regular import statement should be used instead:

 #importing the Kratos Library
 from KratosMultiphysics import *
 from KratosMultiphysics.IncompressibleFluidApplication import *
 # Check that KratosMultiphysics was imported in the main script
 CheckForPreviousImport()
 
 ## ...
 
 def AdaptMesh(self):
     import KratosMultiphysics.MeshingApplication as KMesh # here we are importing the application only for this function
     
     refinement_utils = KMesh.RefinementUtilities()
     Refine = KMesh.LocalRefineTetrahedraMesh(self.model_part)
     
     ## ....

Note that the "as KMesh" part of the import statement is completely optional and is used here to provide a shorcut for the name of the application. The following code uses the full name and is equivalent to the example above.

 def AdaptMesh(self):
     import KratosMultiphysics.MeshingApplication # here we are importing the application only for this function
     
     refinement_utils = KratosMultiphysics.MeshingApplication.RefinementUtilities()
     Refine = KratosMultiphysics.MeshingApplication.LocalRefineTetrahedraMesh(self.model_part)

Adding new applications

All existing applications have been updated to the new format. The name of the module to be imported from Python is the same as the name of the .py file that exists in the folder for the application.