Default values for free.

import numpy as np
import paragami

You can set a default value for whether or not a parameter is free.

a = np.eye(3) + np.random.random((3, 3))
a = 0.5 * (a + a.T)

a_free_pattern = paragami.PSDSymmetricMatrixPattern(size=3, free_default=True)

a_freeflat = a_free_pattern.flatten(a)
print('a_freeflat:\n{}\n'.format(a_freeflat))
print('a:\n{}\n'.format(a_free_pattern.fold(a_freeflat)))

a_freeflat:
[ 0.13919912  0.41973416  0.12037979  0.7396427   0.44432253 -0.06185827]

a:
[[1.32101217 0.48242269 0.85011051]
 [0.48242269 1.4483919  0.81161586]
 [0.85011051 0.81161586 1.6281241 ]]

The default is be overridden by setting the argument free.

a_flat = a_free_pattern.flatten(a, free=False)
print('a_flat:\n{}\n'.format(a_flat))
print('a:\n{}\n'.format(a_free_pattern.fold(a_flat, free=False)))

a_flat:
[1.32101217 0.48242269 0.85011051 0.48242269 1.4483919  0.81161586
 0.85011051 0.81161586 1.6281241 ]

a:
[[1.32101217 0.48242269 0.85011051]
 [0.48242269 1.4483919  0.81161586]
 [0.85011051 0.81161586 1.6281241 ]]

You can change the default by setting the attribute free_default.

# Now this pattern is misnamed!
a_free_pattern.free_default = False
print('a_flat:\n{}\n'.format(a_free_pattern.flatten(a)))

a_flat:
[1.32101217 0.48242269 0.85011051 0.48242269 1.4483919  0.81161586
 0.85011051 0.81161586 1.6281241 ]

An error is raised if free_default is None and free is not specified.

a_free_pattern.free_default = None
try:
    a_free_pattern.flatten(a)
except ValueError as err:
    print('Folding with a_free_pattern raised the following ValueError:\n{}'.format(err))

Folding with a_free_pattern raised the following ValueError:
If ``free_default`` is ``None``, ``free`` must be specified.

Pattern containers override the default values of their contents so you don’t accidentally mix free and non-free flattened values.

dict_pattern = paragami.PatternDict(free_default=True)

dict_pattern['a1'] = paragami.PSDSymmetricMatrixPattern(size=3, free_default=False)
dict_pattern['a2'] = paragami.PSDSymmetricMatrixPattern(size=3, free_default=True)

print('\nThis pattern alone is non-free by default:')
print(dict_pattern['a1'].flatten(a))

print('\nThis pattern alone is free by default:')
print(dict_pattern['a2'].flatten(a))

print('\nBut the dictionary pattern overrides the default:')
param_dict = { 'a1': a, 'a2': a}
print(dict_pattern.flatten(param_dict))

print('\nIf no default is specified, an error is raised ' +
      'so that you do not accidentally mix free and non-free flat values.')
dict_pattern_nodefault = paragami.PatternDict()
try:
    dict_pattern_nodefault.flatten(param_dict)
except ValueError as err:
    print('Folding a container with no default raised the follding ValueError:\n{}'.format(err))

This pattern alone is non-free by default:
[1.32101217 0.48242269 0.85011051 0.48242269 1.4483919  0.81161586
 0.85011051 0.81161586 1.6281241 ]

This pattern alone is free by default:
[ 0.13919912  0.41973416  0.12037979  0.7396427   0.44432253 -0.06185827]

But the dictionary pattern overrides the default:
[ 0.13919912  0.41973416  0.12037979  0.7396427   0.44432253 -0.06185827
  0.13919912  0.41973416  0.12037979  0.7396427   0.44432253 -0.06185827]

If no default is specified, an error is raised so that you do not accidentally mix free and non-free flat values.
Folding a container with no default raised the follding ValueError:
If ``free_default`` is ``None``, ``free`` must be specified.