gvec.util#

GVEC utility module

This module is part of the gvec python package, but also used directly in the tests.

class gvec.util.CaseInsensitiveDict(data=(), /, **kwargs)#

Bases: MutableMapping

A dictionary-like Mutable Mapping where string keys are case-insensitive.

Implements all methods and operations of MutableMapping as well as dict’s copy. Also provides lower_items and lower_keys.

Keys that are not strings will be stored as-is. The structure remembers the case of the last used key, and iter(instance), keys(), items(), iterkeys(), and iteritems() will contain case-sensitive keys. However, querying and contains testing is case insensitive:

cid = CaseInsensitiveDict() cid[‘param’] = ‘value’ cid[‘Param’] == ‘value’ # True

If the constructor, .update, or equality comparison operations are given keys that have equal ``.lower()``s, a ValueError is raised.

copy()#

Return a deep copy.

lower_items()#
lower_keys()#
serialize()#

Recursively serialize this object, converting Mappings to dicts and Iterables to lists.

update([E, ]**F) → None.  Update D from mapping/iterable E and F.#

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

gvec.util.adapt_parameter_file(source: str | Path, target: str | Path, **kwargs)#

Copy the source file to the target file and replace the parameters according to kwargs.

Parameters:

  • source (str or Path) – The path to the source parameter file.

  • target (str or Path) – The path to the target parameter file.

  • **kwargs – Keyword arguments representing the parameters to be replaced. if the value of the key is “!”, the line with the keyword is uncommented, if possible

Raises:

AssertionError – If the number of occurrences for any parameter is not exactly 1.

Notes

  • If no parameters are provided in kwargs, the function simply copies the source file to the target file.

  • The function replaces the parameters in the format key = value, where value is either a sequence of characters containing no whitespace or a single pair of parentheses with any content. The value from kwargs is inserted using the standard python string conversion. There may be a comment, starting with !, after the value.

  • If a parameter already exists in the source file, its value is replaced with the corresponding value from kwargs.

  • If a parameter does not exist in the source file, it is added to the target file.

  • If the value of the key starts with “!”, the line with the keyword is just uncommented. (i.e. “!key=2.5” -> “key=2.5”) If no line with the keyword is found, the key is added with the value, excluding the leading “!” (i.e. value is “!0.5” -> “key=0.5” is added)

Example

>>> adapt_parameter_file(‘/path/to/source.ini’, ‘/path/to/target.ini’, param1=1.2, param2=”(1, 2, 3)”)

gvec.util.axis_from_boundary(parameters: MutableMapping) → MutableMapping#
gvec.util.bspl2gvec(name: Literal['iota', 'pres'], bspl: BSpline | None = None, knots: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, coefs: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, params: dict = {}) → dict#

Translates a scipy B-spline object or B-spline coefficients and knots for either a iota or pressure profile into a dictionary entries that can be handed to adapt_parameter_file.

Parameters:

  • name (str) – profile identifyer, has to be either iota or pres.

  • bspl (scipy.interpolate.BSpline) – scipy BSpline object. If this is not provided knots and coefs are expected.

  • knots (ArrayLike) – Knots for the B-splines. Note that repeated edge knots according to the degree are expected.

  • coefs (ArrayLike) – Coefficients for the B-splines.

  • params (dict, optional) – Dictionary of gvec input parameters that will be adapted. Defaults to {}.

Raises:

  • ValueError – If name is neither iota nor pres.

  • TypeError – If neither bspl nor knots and coefs is provided.

Returns:

Dictionary of gvec input parameters

Return type:

dict

gvec.util.chdir(target: Path | str)#

Contextmanager to change the current working directory.

Using a context has the benefit of automatically changing back to the original directory when the context is exited, even if an exception is raised.

gvec.util.flatten_parameters(parameters: Mapping) → CaseInsensitiveDict#

Flatten parameters from a hierarchical dictionary

gvec.util.flip_parameters_theta(parameters: MutableMapping) → MutableMapping#
gvec.util.flip_parameters_zeta(parameters: MutableMapping) → MutableMapping#
gvec.util.logging_setup()#

Setup default logging configuration for GVEC.

gvec.util.parameters_from_vmec(nml: Mapping) → CaseInsensitiveDict#
gvec.util.read_parameter_file_ini(path: str | Path) → CaseInsensitiveDict#

Read the parameters from the specified parameter file in GVEC-ini format.

Parameters:

path (str | Path) – The path to the parameter file.

Returns:

A mapping (with case insensitive keys) containing the parameters from the parameter file.

Return type:

CaseInsensitiveDict

Example: >>> read_parameter_file_ini(‘/path/to/parameter.ini’) {‘param1’: 1.2, ‘param2’: (1, 2, 3), ‘param3’: {(-1, 0): 0.5, (0, 0): 1.0}}

gvec.util.read_parameters(path: Path | str, format: Literal['ini', 'yaml', 'toml'] | None = None) → CaseInsensitiveDict#
gvec.util.stack_parameters(parameters: Mapping) → CaseInsensitiveDict#

Stack parameters into a hierarchical dictionary

gvec.util.stringify_mn_parameters(parameters: Mapping) → CaseInsensitiveDict#

Serialize parameters into a string

gvec.util.unstringify_mn_parameters(parameters: Mapping) → CaseInsensitiveDict#

Deserialize parameters from a string

gvec.util.write_parameter_file_ini(parameters: Mapping, path: str | Path = 'parameter.ini', header: str = '')#

Write the parameters to the specified parameter file in GVEC-ini format.

Parameters:

  • parameters – A mapping containing the parameters to be written to the parameter file.

  • path – The path to the parameter file.

gvec.util.write_parameters(parameters: Mapping, path: Path | str = 'parameter.ini', format: Literal['ini', 'yaml', 'toml'] | None = None)#