Merge pull request #659 from zickgraf/CapJitPrecompileCategory

Add CapJitPrecompileCategory

Author: zickgraf

CAP/gap/CAP.gd

@@ -232,6 +232,24 @@ DeclareAttribute( "MorphismFilter",
 DeclareAttribute( "TwoCellFilter",
                   IsCapCategory );
 
+#! @Description
+#! The argument is a category $C$.
+#! The output is the GAP type of objects of $C$.
+#! Only available after calling `AddObjectRepresentation`.
+#! @Arguments C
+#! @Returns a GAP type
+DeclareAttribute( "ObjectType",
+                  IsCapCategory );
+
+#! @Description
+#! The argument is a category $C$.
+#! The output is the GAP type of morphisms of $C$.
+#! Only available after calling `AddMorphismRepresentation`.
+#! @Arguments C
+#! @Returns a GAP type
+DeclareAttribute( "MorphismType",
+                  IsCapCategory );
+
 #! @Description
 #! The argument is a category $C$ which is expected to lie in the
 #! filter <C>IsLinearCategoryOverCommutativeRing</C>.

CAP/gap/CategoryMorphisms.gi

@@ -255,6 +255,7 @@ InstallMethod( AddMorphismRepresentation,
 
     category!.morphism_representation := representation;
     category!.morphism_type := NewType( TheFamilyOfCapCategoryMorphisms, representation and MorphismFilter( category ) and IsCapCategoryMorphismRep and HasSource and HasRange and HasCapCategory );
+    SetMorphismType( category, category!.morphism_type );
 
 end );
 
@@ -286,7 +287,7 @@ InstallGlobalFunction( ObjectifyMorphismWithSourceAndRangeForCAPWithAttributes,
     #% CAP_JIT_RESOLVE_FUNCTION
 
     arg_list := Concatenation( 
-        [ morphism, category!.morphism_type, CapCategory, category, Source, source, Range, range ], additional_arguments_list
+        [ morphism, MorphismType( category ), CapCategory, category, Source, source, Range, range ], additional_arguments_list
     );
 
     objectified_morphism := CallFuncList( ObjectifyWithAttributes, arg_list );

CAP/gap/CategoryObjects.gi

@@ -224,6 +224,7 @@ InstallMethod( AddObjectRepresentation,
 
     category!.object_representation := representation;
     category!.object_type := NewType( TheFamilyOfCapCategoryObjects, representation and ObjectFilter( category ) and IsCapCategoryObjectRep and HasCapCategory );
+    SetObjectType( category, category!.object_type );
 
 end );
 
@@ -241,7 +242,7 @@ InstallGlobalFunction( ObjectifyObjectForCAPWithAttributes,
     #% CAP_JIT_RESOLVE_FUNCTION
 
     arg_list := Concatenation(
-        [ object, category!.object_type, CapCategory, category ], additional_arguments_list
+        [ object, ObjectType( category ), CapCategory, category ], additional_arguments_list
     );
 
     return CallFuncList( ObjectifyWithAttributes, arg_list );

CompilerForCAP/doc/Usage.autodoc

@@ -80,11 +80,33 @@ If `enable_compilation` is set to `true`, any basic operation will be compiled w
 If `enable_compilation` is a list of strings, compilation will only happen if the function name
 of the basic operation appears in this list.
 
+@Section Giving hints to the compiler
+@SectionLabel CompilerHints
+
+You can give hints to the compiler to improve the result of the compilation. Compiler hints are attached to the category by making
+`category!.compiler_hints` a record with one or more of the following keys:
+* `category_attributes_names`: a list of names of attributes of the category. If a global variable in the compiled code has the same value
+                               as one of the given attributes of the category, the global variable is replaced by the attribute getter applied to the category.
+                               Background: During the compilation, the compiler resolves attributes occuring in the code and stores them in global variables
+                               called `CAP_JIT_INTERNAL_GLOBAL_VARIABLE_n` (for integers `n` starting from 1). If these variables cannot be replaced,
+                               the resulting code is only valid in the current session.
+* `source_and_range_attributes_from_morphism_attribute`: a record with keys `object_attribute_name`, `morphism_attribute_name`, `source_attribute_getter_name`,
+                                                         and `range_attribute_getter_name`. Replaces the attribute `object_attribute_name` of the source (resp. range)
+                                                         of a morphism by `source_attribute_getter_name` (resp. `range_attribute_getter_name`) applied to
+                                                         the attribute `morphism_attribute_name` of the morphism. Can be used if objects and morphisms can be
+                                                         easily created from the morphism datum anyway. Note: Some simple expressions like integers are NOT replaced.
+
+Note: The compiler can only discover the hints if the category is the first argument of the function.
+
 @Section Stopping the compiler at a certain level
 
 You can use `StopCompilationAtCategory` to prevent the compiler from inlining and optimizing code of a given category.
 You can revert this decision using `ContinueCompilationAtCategory`.
 
+@Section Precompiling categories
+
+You can compile categories and store the result in a file for later use.
+
 @Section Getting information about the compilation process
 
 You can increase the info level of `InfoCapJit` to get information about the compilation process.

CompilerForCAP/examples/CAP_JIT_NEXT_FUNCCALL_DOES_NOT_RETURN_FAIL.g

@@ -18,19 +18,20 @@ compiled_func := CapJitCompiledFunction(
     MyKernelLift,
     [ rows, ZeroMorphism( V, V ), IdentityMorphism( V ) ]
 );;
-tree := SYNTAX_TREE( compiled_func );;
-# check that the fail has been compiled away,
-# that is, we simply return a CAP morphism
-Length( tree.stats.statements ) = 1;
-#! true
-tree.stats.statements[1].type = "STAT_RETURN_OBJ";
-#! true
-StartsWith( tree.stats.statements[1].obj.type, "EXPR_FUNCCALL" );
-#! true
-tree.stats.statements[1].obj.funcref.type = "EXPR_REF_GVAR";
-#! true
-tree.stats.statements[1].obj.funcref.gvar = "ObjectifyWithAttributes";
-#! true
+Display( compiled_func );
+#! function ( cat, mor, test_morphism )
+#!     local cap_jit_morphism_attribute;
+#!     cap_jit_morphism_attribute 
+#!      := RightDivide( UnderlyingMatrix( test_morphism ), 
+#!        SyzygiesOfRows( UnderlyingMatrix( mor ) ) );
+#!     return ObjectifyWithAttributes( rec(
+#!            ), MorphismType( cat ), CapCategory, cat, Source, 
+#!        Source( test_morphism ), Range, ObjectifyWithAttributes( rec(
+#!              ), ObjectType( cat ), CapCategory, cat, Dimension, 
+#!          NrColumns( cap_jit_morphism_attribute ), UnderlyingFieldForHomalg, 
+#!          UnderlyingRing( cat ) ), UnderlyingFieldForHomalg, 
+#!        UnderlyingRing( cat ), UnderlyingMatrix, cap_jit_morphism_attribute );
+#! end
 
 func1 := function( x )
     #% CAP_JIT_RESOLVE_FUNCTION

CompilerForCAP/examples/LinearAlgebraForCAP.g

@@ -2,14 +2,12 @@
 
 #! @Section Examples
 
-LoadPackage( "LinearAlgebra" );
+LoadPackage( "LinearAlgebraForCAP" );
 
 #! @Example
 
 Q := HomalgFieldOfRationals();;
-vec := MatrixCategory( Q :
-    enable_compilation := [ "MorphismBetweenDirectSums" ]
-);;
+vec := MatrixCategory( Q : enable_compilation := true );;
 
 V := VectorSpaceObject( 2, Q );;
 alpha := ZeroMorphism( V, V );;
@@ -32,9 +30,8 @@ Display( SYNTAX_TREE_CODE( tree1 ) );
 #!         return ZeroMorphism( S, T );
 #!     else
 #!         return ObjectifyWithAttributes( rec(
-#!                ), CAP_JIT_INTERNAL_GLOBAL_VARIABLE_3, CapCategory, 
-#!            CAP_JIT_INTERNAL_GLOBAL_VARIABLE_1, Source, S, Range, T, 
-#!            UnderlyingFieldForHomalg, CAP_JIT_INTERNAL_GLOBAL_VARIABLE_2, 
+#!                ), MorphismType( cat ), CapCategory, cat, Source, S, Range, T, 
+#!            UnderlyingFieldForHomalg, UnderlyingRing( cat ), 
 #!            UnderlyingMatrix, 
 #!            UnionOfRows( List( morphism_matrix, function ( row )
 #!                     return UnionOfColumns( List( row, UnderlyingMatrix ) );
@@ -57,9 +54,8 @@ Display( SYNTAX_TREE_CODE( tree2 ) );
 #!         return ZeroMorphism( S, T );
 #!     else
 #!         return ObjectifyWithAttributes( rec(
-#!                ), CAP_JIT_INTERNAL_GLOBAL_VARIABLE_3, CapCategory, 
-#!            CAP_JIT_INTERNAL_GLOBAL_VARIABLE_1, Source, S, Range, T, 
-#!            UnderlyingFieldForHomalg, CAP_JIT_INTERNAL_GLOBAL_VARIABLE_2, 
+#!                ), MorphismType( cat ), CapCategory, cat, Source, S, Range, T, 
+#!            UnderlyingFieldForHomalg, UnderlyingRing( cat ), 
 #!            UnderlyingMatrix, 
 #!            UnionOfRows( List( morphism_matrix, function ( row )
 #!                     return UnionOfColumns( List( row, function ( s )
@@ -70,4 +66,20 @@ Display( SYNTAX_TREE_CODE( tree2 ) );
 #!     return;
 #! end
 
+KernelEmbedding( alpha );;
+Display( Last( vec!.compiled_functions.KernelEmbedding ) );
+#! function ( cat, morphism )
+#!     local cap_jit_morphism_attribute;
+#!     cap_jit_morphism_attribute 
+#!      := SyzygiesOfRows( UnderlyingMatrix( morphism ) );
+#!     return ObjectifyWithAttributes( rec(
+#!            ), MorphismType( cat ), CapCategory, cat, Source, 
+#!        ObjectifyWithAttributes( rec(
+#!              ), ObjectType( cat ), CapCategory, cat, Dimension, 
+#!          NrRows( cap_jit_morphism_attribute ), UnderlyingFieldForHomalg, 
+#!          UnderlyingRing( cat ) ), Range, Source( morphism ), 
+#!        UnderlyingFieldForHomalg, UnderlyingRing( cat ), UnderlyingMatrix, 
+#!        cap_jit_morphism_attribute );
+#! end
+
 #! @EndExample

CompilerForCAP/examples/PrecompileLinearAlgebraForCAP.g

@@ -0,0 +1,41 @@
+#! @Chapter Examples and tests
+
+#! @Section Examples
+
+LoadPackage( "LinearAlgebraForCAP" );
+
+#! @Example
+
+QQ := HomalgFieldOfRationals( );;
+
+# be careful not to use `MatrixCategory` because attributes are not supported
+category_constructor := field -> MATRIX_CATEGORY( field );;
+given_arguments := [ QQ ];;
+compiled_category_name := "MatrixCategoryPrecompiled";;
+package_name := "LinearAlgebraForCAP";;
+operations := [
+    "AdditionForMorphisms",
+    "PreCompose",
+    "KernelEmbedding",
+];;
+
+filepath := "precompiled_categories/MatrixCategoryPrecompiled.gi";;
+old_file_content := ReadFileFromPackageForHomalg( package_name, filepath );;
+
+CapJitPrecompileCategory(
+    category_constructor,
+    given_arguments,
+    package_name,
+    compiled_category_name :
+    operations := operations
+);
+
+new_file_content := ReadFileFromPackageForHomalg( package_name, filepath );;
+
+old_file_content = new_file_content;
+#! true
+
+MatrixCategoryPrecompiled( QQ );
+#! Category of matrices over Q
+
+#! @EndExample

CompilerForCAP/gap/CompilerForCAP.gi

@@ -191,6 +191,18 @@ InstallGlobalFunction( CapJitCompiledFunction, function ( func, jit_args )
 
     od;
 
+    if Length( jit_args ) > 0 and IsCapCategory( jit_args[1] ) then
+        
+        if debug then
+            compiled_func := ENHANCED_SYNTAX_TREE_CODE( tree );
+            Display( compiled_func );
+            Display( "apply CapJitAppliedCompilerHints" );
+        fi;
+        
+        tree := CapJitAppliedCompilerHints( tree, jit_args[1] );
+        
+    fi;
+    
     if debug then
 
         compiled_func := ENHANCED_SYNTAX_TREE_CODE( tree );

CompilerForCAP/gap/CompilerHints.gd

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+# CompilerForCAP: Speed up computations in CAP categories
+#
+# Declarations
+#
+#! @Chapter Improving and extending the compiler
+
+#! @Section Compilation steps
+
+#! @Description
+#!   Applies all compiler hints (see <Ref Sect="Section_CompilerHints" />) to <A>tree</A>.
+#! @Returns a record
+#! @Arguments tree, category
+DeclareGlobalFunction( "CapJitAppliedCompilerHints" );
+
+#! @Description
+#!   Applies the compiler hint `category_attribute_names` (see <Ref Sect="Section_CompilerHints" />) to <A>tree</A>.
+#!   Assumes that <A>category</A> is the first argument of the function defined by <A>tree</A>.
+#! @Returns a record
+#! @Arguments tree, category
+DeclareGlobalFunction( "CapJitReplacedGlobalVariablesByCategoryAttributes" );
+
+#! @Description
+#!   Applies the compiler hint `source_and_range_attributes_from_morphism_attribute` (see <Ref Sect="Section_CompilerHints" />) to <A>tree</A>.
+#! @Returns a record
+#! @Arguments tree, category
+DeclareGlobalFunction( "CapJitReplacedSourceAndRangeAttributes" );