pysep.io.nml.control package

Submodules

pysep.io.nml.control.control module

Author: Thomas M. Boudreaux

Created: April 2021

Last Modified: June 2021

Module to handel both dsep run (cards in the control namelist file) as well as the entire control namelist file.

Classes

crun

Individual card in control namelist file, such as an evolutionary or a rescaling run.

cnml

control namelist file object. These can be made up of up to 50 crun objects along with a number of attributes not tied into a crun object.

class pysep.io.nml.control.control.cnml(runs: list, unit=14, **kwargs)

Bases: object

Control namelist file object representation. This object is the equivilent to the control namelist file used when running dsep. It can represent all the same information which a control namelist file representes. Moreover, it can be written to disk in the form of a fortran namelist file so that dsep can read it in. Because it is a python object though it can also be programatically modified and tested.

The cnml object is made up of some set of crun objects as well as any additional variables which the control namelist file might store outside of an actual dsep run (such as many of the logical flags).

When writing to disk (for symlinking) cnml will write a namelist file to a temporaty file in /var/tmp and then symbolically link a unit file in the current working directory to that temporary file. Therefore, the actual control namelist file will be deleted when the cnml instance goes out of scope. To combat this you can explicitly save a namelist representation of the cnml to disk using the save method.

Finally, when pickled, if the cnml has been locally symlinked (and therefore has open a temporary file) that file will be explicitly deleted as file objects cannot be pickled. Therefore you cannot symlink a cnml object, pickle it, load it, and start back where you were. You have to symlink it again after loading the pickle dump.

runs

A list of crun objects, one for each dsep run (such as a rescaling run or an evolutionary run)

Type

list of crun objects

unit

The unit number to symbolically link the control namelist file to.

Type

int, default=14

dsepAttrs

Dictionary of all the different attributes which the control namelist file can store. These are stored as key value pairs with the key being the variale name and the value being the variable value. These are passed to the constructor as an arbitrary number of keyword arguments which will all (aside from unit) become key value pairs in the dsepAttrs dictionary.

Type

dict of control namelist file key value pairs

add_key(key: str, value)

Add a new key to control namelist. If the key is not created then create it if the key is already present raise an error.

Parameters

  • key (str) – The name of any class instance attribute which is defined.

  • value – Any data to store in the class instance attribute named key

Returns

Return type

None

Raises

KeyError – If key is already in the kind card

append_run_card(newCard: pysep.io.nml.control.control.crun)

Add a new run card to cnml object

Parameters

newCard (crun) – New card to append to end of runs list

as_dict(generalizePaths=False) → dict

Return a python dictionary representation of the cnml object.

Parameters

generalizePaths (bool, default=False) – If set to true the local computer absolute path to DSEPRoot will be replaced with %DSEPRoot% at all occurences. This is the generatlized placeholder for DSEPRoot in pysep. This is helpful for portability.

Returns

dictRepr – Dictionary representation.

Return type

dict

If already locally symlinked then remove the unit file fort.<unit> and set the state of the cnml instance to no longer be locally symlinked.

copy() → pysep.io.nml.control.control.cnml

Deep copy method for nml object.

Returns

newone – copy of this cnml object without any open NamedTemporaryFile if that had been opened and set to not symlinked.

Return type

pysep.io.nml.control.cnml

duplicate_run_card(idxS: int, idxD: Optional[int] = None, loosed: bool = True)

Inserts a duplicate of the run card at position idxS into the list at position idxD

Parameters

  • idxS (int) – Index source, the run card to be duplicated

  • idxD (int, optional) – Index Destination, the location where the duplicated run card will be stored in the runs list. By default the duplicated run card will be inserted onto the end of the list.

  • loosed (bool, default=True) – If true then descriptions will be automatically removed when there are more than two present, if false then they will not be (this may result in runtime errors)

insert_run_card(newCard: pysep.io.nml.control.control.crun, idx: int)

Insert a new run card somewhere into the runs list

Parameters

  • newCard (crun) – New card to insert somwhere into the runs list

  • idx (int) – Index to insert card into

Raises

  • RuntimeError – User would add more than 50 run cards to control namelist

  • RuntimeError – User would add more than 2 descrip parameters to namelist

iter_kinds(kind: int)

Iterator to jump through all cruns of a particular kind (either 0 or 1)

Parameters

kind (int) – kind of crun to iterate through. If 1 then iterator will yield evolutionary runs, if 2 then iterator will yield rescaling runs. This is done simply by filtering by the kindrun parameter.

Yields

kindCard (crun) – next crun of the particular kind

Symbolically link the control namelist file to the correct unit file in the current working directory. Instead of saving the cnml file to the current working directory or some user defined path, this function saves the cnml file to a NamedTemporaryFile in /var/tmp (on a linux machine at least). This has the advantage of not cluttering up the local directory as well as automatically deleting the nml file after you send the cnml object out of scope. Once the temporary file has been opned f90nml writes the dicitonary version of the data stored in this object to it. Finally that temporary file is symbolically linked to fort.<unit> in the current working directory.

Because we need to keep the file object in scope as long as we want to be able to access the namelist file, the file object is stored as a class attribute, f.

If a file or symlink called fort.<unit> already exists in the current working directory when this method is called it will be deleted and replaced with the symbolic link created by this method.

Raises

OSError – If the NamedTemporaryFile was unable to be properly opened.

remove_last_run_card() → pysep.io.nml.control.control.crun

Pop the final run card from the cnml obeject

Returns

popped – Final run card, no longer present in runs list

Return type

crun

remove_run_card(idx: int) → pysep.io.nml.control.control.crun

Pop a specific run card from the runs list

Parameters

idx (int) – Index to pop from runs list

Returns

popped – Run card popped

Return type

crun

save(path: str) → bool

Save cnml file as a fortran namelist file to disk.

Parameters

path (str) – Path to save namelist file to. If path exists already it will be overwritten.

Returns

Check whether namelist file was creates sucessfully. Will be true if file exists and false if it was not able to be creates.

Return type

bool

class pysep.io.nml.control.control.crun(kindrn, numrun, **kwargs)

Bases: object

Individual card in control namelist file, such as an evolutionary or a rescaling run.

RUNTYPES

Two types of runs can be defined for dsep, these are stored here. An index of 1 returns EVOLVE for an evolutionary run and an index of 2 returns RESCALE for a rescaling run.

Type

dict of strings

kindrn

Index of run type per RUNTYPES

Type

int

numrun

Index specifiing which run number for a single execution of the dsep program this crun represents.

Type

int

allownewset

If true allows [] on crun to not just update elements but also create new elements

Type

bool (False)

RUNTYPES = {1: 'EVOLVE', 2: 'RESCALE'}
add_key(key: str, value)

Add a new key to the kind card. If the key is not created then create it if the key is already present raise an error.

Parameters

  • key (str) – The name of any class instance attribute which is defined.

  • value – Any data to store in the class instance attribute named key

Returns

Return type

None

Raises

KeyError – If key is already in the kind card

as_dict() → dict

Return a Dictionary representation of the DSEP run object

Returns

runDict – Dictionary representation of the DSEP run object.

Return type

dict

copy() → pysep.io.nml.control.control.crun

Preform a deep copy of the crun object

Returns

newone – New crun object with the same attribute values as the parent but not the same references. May be modified independently.

Return type

pysep.io.nml.control.control.crun

remove_key(key: str)

Remove a key from a crun card

Parameters

key (str) – Key to remove from dict

Returns

Value removed

Return type

popped

update_key(key: str, value)

Setitem using key where key is simply resolved to the name of an attribute of the class instance. Equivilent to crun().__dict__[key]. Note that key must already exist as an attribute of the class

Parameters

  • key (str) – The name of any class instance attribute which is defined.

  • value – Any data to store in the class instance attribute named key

Returns

Return type

None

Raises

KeyError – If there is no attribute named key in the instance of the class.

pysep.io.nml.control.control.load(path: str) → pysep.io.nml.control.control.cnml

Load a control namelist file from disk (note that this loads a fortran control namelist file into a cnml object, NOT a pickeled cnml object back into memory, for that use pickle.load)

Parameters

path (str) – Path to control namelist file to load.

Returns

Control namelist file loaded from disk with all paths updated to local machine valid paths (opecalex is offender here)

Return type

pysep.io.nml.control.cnml

pysep.io.nml.control.utils module

Author: Thomas M. Boudreaux

Created: September 2021

Last Modified: September 2021

Utility Functions for converting cnml to dictionary and back

Functions

  • crun_from_dict

    Load a crun object from a dictionary.

  • cnml_from_dict

    Return a cnml object from a dictionary.

pysep.io.nml.control.utils.cnml_from_dict(params: dict) → pysep.io.nml.control.control.cnml

Return a cnml object from a dictionary.

Parameters

params (dict) – Dictionary containing all the required information to rebuild the cnml object, including a list of all the crun dictionaries.

Returns

outCnml – cnml object

Return type

pysep.io.nml.control.control.cnml

pysep.io.nml.control.utils.crun_from_dict(params: dict) → pysep.io.nml.control.control.crun

Load a crun object from a dictionary.

Parameters

params (dict) – Dictionary with crun parameters in it along with the key, “kindrun”.

Returns

run – crun object with the parameters from params loaded and set.

Return type

pysep.io.nml.control.control.crun

Module contents

Module to interact with the control namelist file which dsep needs to run.