farn.farn¶
Functions
|
Create the case folder structure for the passed in cases. |
|
Create case list files for the specified nest levels. |
|
Create cases based on the layers, filter expressions and samples defined in the passed farn dict. |
|
Create the case specific paramDict files in the case folders of the passed in cases. |
|
Run sampling and create the samples inside all layers of the passed in farn dict. |
|
Execute the given command set in the case folders of the passed in cases. |
|
Run farn. |
- farn.farn.create_case_folders(cases: MutableSequence[Case]) int¶
Create the case folder structure for the passed in cases.
- Parameters:
cases (MutableSequence[Case]) – cases the case folders shall be created for.
- Returns:
number of case folders created.
- Return type:
int
- farn.farn.create_case_list_files(cases: MutableSequence[Case], target_dir: Path | None = None, levels: int | Sequence[int] | None = None) list[Path]¶
Create case list files for the specified nest levels.
Case list files are simple text files containing a list of paths to all case folders that share a common nest level within the case folder structure. I.e. a case list file created for level 0 contains the paths to all case folders on level 0. A case list file for level 1 contains the paths to all case folders on level 1, and so on.
These lists can be used i.e. in a batchProcess to execute shell commands in all case folders of a specific nest level inside the case folder structure.
- Parameters:
cases (MutableSequence[Case]) – cases the case list files shall be created for
target_dir (Path, optional) – directory in which the case list files shall be created. If None, current working directory will be used., by default None
levels (Union[int, Sequence[int], None], optional) – list of integers indicating the nest levels for which case list files shall be created. If missing, by default a case list file for the deepest nest level (the leaf level) will becreated., by default None
- Returns:
The case list files that have been created (returned as a list of Path objects)
- Return type:
list[Path]
- farn.farn.create_cases(farn_dict: MutableMapping[Any, Any], case_dir: Path, *, valid_only: bool = False) Cases¶
Create cases based on the layers, filter expressions and samples defined in the passed farn dict.
Creates case objects for all cases derived by recursive permutation of layers and the case specific samples defined per layer. create_cases() creates one distinct case object for each case, holding all case attributes (parameters) set to their case specific values.
Optionally, only _valid_ cases can be returned, i.e. cases which fulfill the filter criteria configured for the respective layer. Invalid cases then get excluded.
Note: The corresponding case folder structure is not yet created by create_cases(). Creating the case folder structure is the responsibility of create_case_folder_structure(). However, the case_dir argument is passed in to allow create_cases() to already document in each case object its _intended_ case folder path. This information is then read and used in create_case_folder_structure() to actually create the case folders.
- Parameters:
farn_dict (MutableMapping) – farn dict. The farn dict must be sampled, i.e. samples must have been generated for all layers defined in the farn dict.
case_dir (Path) – directory the case folder structure is (intended) to be generated in.
valid_only (bool) – whether or not only valid cases shall be returned, i.e. cases which fulfill the filter criteria configured for the respective layer., by default False
- Returns:
list of case objects representing all created cases.
- Return type:
- farn.farn.create_param_dict_files(cases: MutableSequence[Case]) int¶
Create the case specific paramDict files in the case folders of the passed in cases.
paramDict files contain the case specific parameters, meaning, via the paramDict files the case specific values for all parameters get distributed to and persisted in the case folders.
- Parameters:
cases (MutableSequence[Case]) – cases the paramDict file shall be created for
- Returns:
number of paramDict files created
- Return type:
int
- farn.farn.create_samples(farn_dict: SDict[str, Any]) None¶
Run sampling and create the samples inside all layers of the passed in farn dict.
Creates the _samples element in each layer and populates it with the discrete samples generated for the parameters defined and varied in the respective layer. In case the _samples element already exists in a layer, it will be overwritten.
- Parameters:
farn_dict (SDict[str, Any]) – farn dict the samples shall be created in
- farn.farn.execute_command_set(cases: MutableSequence[Case], command_set: str, *, batch: bool = True, test: bool = False) int¶
Execute the given command set in the case folders of the passed in cases.
- Parameters:
cases (MutableSequence[Case]) – cases for which the specified command set shall be executed.
command_set (str) – name of the command set to be executed, as defined in farnDict
batch (bool, optional) – if True, executes the given command set in batch mode, i.e. asynchronously, by default False
test (bool, optional) – if True, executes command set in only first case folder where command set is defined, by default False
- Returns:
number of case folders in which the command set has been executed
- Return type:
int
- farn.farn.run_farn(farn_dict_file: str | PathLike[str], *, sample: bool = False, generate: bool = False, command: str | None = None, batch: bool = False, test: bool = False) Cases¶
Run farn.
Runs the sampling for all layers as configured in farn dict, generates the corresponding case folder structure and executes user-defined shell command sets in all case folders.
- Parameters:
farn_dict_file (Union[str, os.PathLike[str]]) – farnDict file. Contains the farn configuration.
sample (bool, optional) – if True, runs the sampling defined for each layer and saves the sampled farnDict file with prefix sampled., by default False
generate (bool, optional) – if True, generates the folder structure that spawns all layers and cases defined in farnDict, by default False
command (Union[str, None], optional) – executes the given command set in all case folders. The command set must be defined in the commands section of the applicable layer in farnDict., by default None
batch (bool, optional) – if True, executes the given command set in batch mode, i.e. asynchronously, by default False
test (bool, optional) – if True, runs only first case and returns, by default False
- Returns:
List containing all valid leaf cases.
- Return type:
- Raises:
FileNotFoundError – if farn_dict_file does not exist