When use secp256k1_fe_normalize(_weak) ?

[PeterMacGonagan]

Hello,

Thanks to your library, I've recoded how elliptical addition works.
According to my tests, it works... :)
However, I don't really know when I should normalize my results (except at the end)?

I use the following functions:

    secp256k1_fe_sqr(&l2, &l);        
    secp256k1_fe_negate(&mx3, x3, 1);  
    secp256k1_fe_add(&x13, &mx3);      
    secp256k1_fe_mul(y3, &l, &x13);    

    secp256k1_fe_normalize_weak(x3); 
    secp256k1_fe_normalize_weak(y3); 

Could you please help me?
After which function should I normalize my results, please?
Notes: I don't need to use any "safety" functions because my aim is to generate the logical equations equivalent to elliptic addition.
I only use field elements fe (not ge or gej).

[real-or-random]

Objects of type secp256k1_fe implicitly carry a magnitude (an integer in [0, 32]), and whether they are normalized (a boolean). If a secp256k1_fe is normalized, it is implied that its magnitude <= 1. These two values are not explicitly present materialized as fields of the secp256k1_fe struct, but they need to be tracked implicitly (unless in the tests when the VERIFY macro is defined).

The functions that operate on field elements also operate on these two values. See the docs in src/field.h, e.g., for secp256k1_fe_sqr:

secp256k1/src/field.h

Lines 270 to 277 in cc55757

	/** Square a field element.
	*
	* On input, a must be a valid field element; r does not need to be initialized. The magnitude
	* of a must not exceed 8.
	* Performs {r = a**2}
	* On output, r will have magnitude 1, but won't be normalized.
	*/
	static void secp256k1_fe_sqr(secp256k1_fe *r, const secp256k1_fe *a);

As a user of these functions, it's your responsibility to adhere to the pre-conditions (e.g., "The magnitude of a must not exceed 8."), and then you are guaranteed the post-conditions (e.g., "On output, r will have magnitude 1, but won't be normalized."). When you have a secp256k1_fe that doesn't adhere to the pre-conditions of a function that you would like to call, you can call secp256k1_fe_normalize_weak first to change the magnitude to 1, or call secp256k1_fe_normalize first to additionally ensure that the secp256k1_fe is normalized.

In the tests (when VERIFY is defined), it is checked that you don't violate the pre-conditions of these functions.

[PeterMacGonagan]

Thank you very much for your explanations.