====== Collect ======
----
====Description====
  * ''Collect[var1, var2]'' collects together terms involving the same powers of specified vars.

  * ''Collect[var1, var2, ..., transformations]'' or ''%%Collect[var1, var2, ..., [Simplifications: transformations]]%%'' additionally applies specified  transformations to the expression that forms the coefficient of each term obtained. 

  * In the case of tensorial vars, ''Collect'' will insert [[documentation:ref:Kronecker delta|Kronecker deltas]] or [[documentation:ref:metric tensor|metric tensors]] in order to "uncontract" indices and factor out tensorial parts.


  * In the case of scalar vars, the behaviour of ''Collect'' is similar to other CASs. 

  * To prevent expand of symbolic terms when collecting tensors one can use option ''%%Collect[[var1, var2, ..., [ExpandSymbolic: false]]%%''
====Examples====

----

Collect terms involving ''x'':
<sxh groovy; gutter: false>
println Collect['x'] >> 'a*x + b*x + с*x**2 + d*x**2 + f*e'.t
</sxh>
<sxh plain; gutter: false>
   > (a + b)*x + (c + d)*x**2 + f*e
</sxh>

----

Collect powers of ''x'' and factor coefficients:
<sxh groovy; gutter: false>
println Collect['x', Factor] >> '(1 + a + x)**4'.t
</sxh>
<sxh plain; gutter: false>
   > x**4 + 4*x**3*(a+1) + 6*x**2*(a+1)**2 + 4*(a+1)**3*x + (a+1)**4
</sxh>

----

Collect terms involving tensor ''A_i'':
<sxh groovy; gutter: false>
println Collect['A_i'] >> 'A_m*B_n + A_n*C_m + B_n*C_m'.t
</sxh>
<sxh plain; gutter: false>
   > A_{a}*(C_{m}*d_{n}^{a} + B_{n}*d_{m}^{a}) + B_{n}*C_{m}
</sxh>

----

Collect terms involving same tensorial function ''F_ij[x_ab]'':
<sxh groovy; gutter: false>
def t = 'F_ij[t_ab]*t^ij + F_ab[t_pq]*f^ba + F_ij[f_ij]*t^ij + F_ij[f_ij]*f^ji'.t
println Collect['F_ij[a_ij]'] >> t
</sxh>
<sxh plain; gutter: false>
   > (t^{ij}+f^{ji})*F_{ij}[t_{ab}]+(t^{ij}+f^{ji})*F_{ij}[f_{ij}]
</sxh>

----


Collect with respect to two variables:
<sxh groovy; gutter: false>
def t = 'A_a * B^b + A^b * B_a + A_a * C^b + A^b * D_a'.t
println Collect['A_m', 'B_m'] >> t
</sxh>
<sxh plain; gutter: false>
   > A_c*B^d*(d_a^c*d^b_d+g_ad*g^bc)+(C^b*d_a^c+g^bc*D_a)*A_c
</sxh>

----


By default ''Collect'' will expand all expressions:
<sxh groovy; gutter: true>
def t = '(a+b)**2 * A_a * B^b + A^b * B_a'.t
println Collect['B_m'] >> t
</sxh>
<sxh plain; gutter: false>
   > B_{c}*((b**2+a**2+2*b*a)*A_{a}*g^{bc}+A^{b}*d_{a}^{c})
</sxh>
To prevent this overhead one can use:
<sxh groovy; gutter: true; first-line: 3>
println Collect['B_m', [ExpandSymbolic: false]] >> t
</sxh>
<sxh plain; gutter: false>
   > B_{c}*((a+b)**2*A_{a}*g^{bc}+A^{b}*d_{a}^{c})
</sxh>


----

====See also====
  * Related guides: [[documentation:guide:applying_and_manipulating_transformations]], [[documentation:guide:list_of_transformations]]
  * Related transformations: [[documentation:ref:collectnonscalars]]
  * JavaDocs: [[http://api.redberry.cc/redberry/1.1.9/java-api/cc/redberry/core/transformations/collect/CollectTransformation.html| CollectTransformation]]
  * Source code: [[https://bitbucket.org/redberry/redberry/src/tip/core/src/main/java/cc/redberry/core/transformations/collect/CollectTransformation.java|CollectTransformation.java]]