document objects with memory #6174

ThomasBreuer · 2025-12-11T16:47:04Z

addresses #6173

fingolfin · 2025-12-12T13:40:55Z

lib/memory.gd

+##  It may, however, happen that some &GAP; function runs into an error
+##  when it is called with elements with memory.
+##  In such cases, probably a method for elements with memory is missing,
+##  and perhaps some existing methods are installed with too weak
+##  requirements.


As an end user, I think I'd find this paragraph frustrating: it describes a problem but gives no hint as to how to resolve it.

Perhaps we can offer some solutions:

add your own method, by looking at the methods in lib/memory.gi and adapting them

contact GAP support / write an issue and requesting this, and we might add it for you

.... anything else?

Also perhaps we could list which operations are currently supported / "wrapped"?

It might also make sense that these things are written mainly with groups in mind, and are tested relatively well for permutations and (quadratic) matrices, and nothing else.

Good point.
I will provide a utility function that creates an overview of the currently supported methods for objects with memory.

Based on our last discussion, it seems you are working on a serious text addressing this point.

Which I think is great, but perhaps we should not let the perfect be the enemy of the good, and first get this PR merged? It seems to me that this point here could already be improved by stating something like. "In this case, additional methods may have to be defined. Please contact GAP support if you run into such a problem and need help."

This can then later be replaced by your better text. But at least the rest of this PR does not need to stay open for an extended time, and people can benefit from it sooner.

fingolfin · 2025-12-12T13:41:00Z

lib/memory.gd

+#############################################################################
+##
+##  <#GAPDoc Label="objwithmemory">
+##  The idea behind objects with memory is as follows.


Other communities refer to this as "tracing" / "tracing operations". Perhaps we could bring that up, briefly, it might help some people?

fingolfin · 2025-12-12T14:46:13Z

lib/memory.gd

+##
+DeclareOperation( "StripMemory", [ IsObject ] );
+
+DeclareOperation( "ForgetMemory", [ IsObject ] );


I was wondering why we even need ForgetMemory ; looking at the methods defined here in GAP, it would seem that ForgetMemory(x); could always be replaced by x := List(x, StripMemory);.

But it turns out it is mainly useful due to its method installed in the genss ("for a stabilizer chain") and orb ("for an orbit object") packages. Then recog uses the one in genss, which in turn uses the one in orb.

fingolfin · 2025-12-12T14:47:31Z

lib/memory.gd

+
+DeclareOperation( "ForgetMemory", [ IsObject ] );
+
+DeclareGlobalFunction( "StripStabChain" );


It seems to me that StripStabChain really should be turned into a method for ForgetMemory -- and also that it should in turn perhaps make use of ForgetMemory ?

fingolfin · 2025-12-12T14:51:09Z

lib/memory.gd

+
+DeclareOperation( "ForgetMemory", [ IsObject ] );
+
+DeclareGlobalFunction( "StripStabChain" );


It seems to me that StripStabChain really should be turned into a method for ForgetMemory -- and also that it should in turn perhaps make use of ForgetMemory ?

UPDATE: ah I see you in fact did change it to use ForgetMemory, excellent!

Logically, StripStabChain does what ForgetMemory is intended for.
However, stabilizer chains are plain records, and installing a method for a record would require some additional checks. Since StripStabChain is not used in the library, I left the name and kept the function undocumented.

fingolfin · 2025-12-12T14:51:13Z

lib/memory.gd

+##
+DeclareOperation( "StripMemory", [ IsObject ] );
+
+DeclareOperation( "ForgetMemory", [ IsObject ] );


I was wondering why we even need ForgetMemory ; looking at the methods defined here in GAP, it would seem that ForgetMemory(x); could always be replaced by x := List(x, StripMemory);.

But it turns out it is mainly useful due to its method installed in the genss ("for a stabilizer chain") and orb ("for an orbit object") packages. Then recog uses the one in genss, which in turn uses the one in orb.

My interpretation was that the main purpose of ForgetMemory is that it works in place. This is how the function StripStabChain uses it.
By not documenting the function, I have postponed the decision whether the function is needed.

fingolfin · 2025-12-12T15:14:23Z

lib/memory.gd

+
+DeclareGlobalFunction( "StripStabChain" );
+
+DeclareGlobalFunction( "CopyMemory" );


I am not aware of any code using this. It seems rather dangerous. Ah well.

fingolfin · 2025-12-12T15:22:54Z

lib/memory.gi

      return ObjWithMemory( slp, b!.n, b!.el );
+#T why can't we return b?


Huh, beats me. The line was added by checks notes one Thomas Breuer, in PR #5875, but to be fair, the code before was essentially equivalent.

I'd be willing to change it and try what happens...?

Suggested change

return ObjWithMemory( slp, b!.n, b!.el );

#T why can't we return b?

return b;

fingolfin · 2025-12-12T15:23:22Z

lib/memory.gi

      return ObjWithMemory( slp, a!.n, a!.el );
+#T why can't we return a?


Suggested change

return ObjWithMemory( slp, a!.n, a!.el );

#T why can't we return a?

return a;

fingolfin · 2025-12-12T15:24:13Z

lib/memory.gi

      return ObjWithMemory( slp, 0, a!.el );
+#T why can't we return a?


Suggested change

return ObjWithMemory( slp, 0, a!.el );

#T why can't we return a?

return a;

fingolfin · 2025-12-12T15:26:57Z

This is great, thanks a lot @ThomasBreuer ! I only left some minor nitpicks

Concerning the question what to do when objects with memory cause GAP errors, add and document `MethodsForObjWithMemory`. For better reference, document also `MethodsOperation`. And fix some GAPDoc syntax.

document objects with memory

c115381

lgoettgens linked an issue Dec 12, 2025 that may be closed by this pull request

Document objects with memory #6173

Open

fingolfin approved these changes Dec 12, 2025

View reviewed changes

ThomasBreuer added 2 commits December 18, 2025 13:09

address comments

77680eb

Concerning the question what to do when objects with memory cause GAP errors, add and document `MethodsForObjWithMemory`. For better reference, document also `MethodsOperation`. And fix some GAPDoc syntax.

changed a reference

496fe14


		DeclareOperation( "ForgetMemory", [ IsObject ] );

		DeclareGlobalFunction( "StripStabChain" );


		DeclareGlobalFunction( "StripStabChain" );

		DeclareGlobalFunction( "CopyMemory" );

		return ObjWithMemory( slp, b!.n, b!.el );
		#T why can't we return b?

	return ObjWithMemory( slp, b!.n, b!.el );
	#T why can't we return b?
	return b;

		return ObjWithMemory( slp, a!.n, a!.el );
		#T why can't we return a?

	return ObjWithMemory( slp, a!.n, a!.el );
	#T why can't we return a?
	return a;

		return ObjWithMemory( slp, 0, a!.el );
		#T why can't we return a?

document objects with memory #6174

Are you sure you want to change the base?

document objects with memory #6174

Uh oh!

Conversation

ThomasBreuer commented Dec 11, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fingolfin commented Dec 12, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants