Python API¶

Below is the automatically generated documentation of PreciSo.

preciso¶

preciso.preciso.add_logo(f, x_frac, y_frac, scale, alpha)¶

Add an image to the figure (not the axes) f: a matplotlib figure instance. path: the string path to the image to add to the figure. x_frac: the fraction of the x dimension of the figure to set the offset to.

Must be a float.

y_frac: the fraction of the y dimension of the figure to set the offset to.: Must be a float.

scale: the float scale by which to multiply to the image pixel dimensions. alpha: the alpha to set the inserted image to

Set the figure dpi to the same as screen dpi.

Use this like: f = add_logo(f, ‘mah_business_logo.png’,x_frac=0.5, y_frac=0.5, scale=0.5, alpha=0.15) for setting a watermark. This should put the center of the image in the center of the figure at half it’s original size.

preciso.preciso.fillTemplate(template_string, values)¶

Fills-in a template that complies with Jinja2 convention. Variables appear as {{variable}} in the template.

Parameters

template_string (str) – The template to fill-in, in plain-text format.
values (dict) – A dictionnary containing variables to replace (keys) and values to put in place (values).

Returns

filled_template (str) – The template, with variables replaced by their values. If there are keys without matching values, they will be ignored (i.e replaced by an empty string).

Examples

>>> import preciso
>>> template = "Hello {{ something }} !"
>>> variables = {"something":"World"}
>>> preciso.fillTemplate(template, variables)
'Hello world !'
>>> preciso.fillTemplate(template, {"somessshing":"World"})
'Hello  !'

preciso.preciso.runSimulation(inputFileName, temp=True, write_limit=100, nodes=None, n_samples=2, debug=False, save_title=None, save_target_path=None, save_mode=None)¶

Runs PreciSo in a temporary folder (default), using provided Input File and gives results in the form of a PrecisoResults object. Run in temporary directories is not supported on Windows currently. It will issue a warning and fallback to temp=False.

Parameters

inputFileName (pathlib.Path object or str) – The path to the input file to use in Preciso. Can be given either as a pathlib.Path object (recommended as it is cross-plateform) or as a str that complies with the computer’s filesystem.
temp (bool) – If True, PreciSo will run in a temporary folder, and its results files will be read and outputed. All files will be discarded at the end. If false, run_input_file is directly called and output files will be created in current working directory.
write_limit (int) – The maximum total size of the files written by PreciSo, in Megabytes. It prevents PreciSo from filling up your computer’s hard drive. Default value is 100MB. If write_limit is of a type different than int, no limit is set. Windows is not supported, there will be no limit on this plateform.
nodes (List of int (optional)) – The id of the node(s) for which we want the precipitates distribution. Default is [0].
save_title (str) – Specify if the results and parameters are to be saved in an HDF5 file (for testing purposes for now). In that case, this is the name of the saved file. Make sure its extension is ‘.hdf5’
save_target_path (str or Pathlib.path) – Specify only if save_title is set. The directory where the HDF5 file will be saved. Default is current directory.
save_mode (char) – Specify only if save_title is set. The opening mode for the save file. Default is ‘x’ to prevent overwritting existing data; use ‘w’ to bypass.

Returns

out (preciso.Results object) – An object that stores the results from a PreciSo simulation.

preciso.results¶

class preciso.results.Results(input_file, results_directory, output, nodes, n_samples)¶

Bases: object

Class for manipulating PreciSo simulation results.

Parameters

input_file (pathlib.Path object or str) – The path to the input file to use in Preciso. Can be given either as a pathlib.Path object (recommended as it is cross-plateform) or as a str that complies with the computer’s filesystem.
results_directory (pathlib.Path object or str) – The path to directory where Preciso wrote its output files. Can be given either as a pathlib.Path object (recommended as it is cross-plateform) or as a str that complies with the computer’s filesystem.
output (str) – The standard output captured during the run of preciso.
nodes (List of int (optional)) – The id of the node(s) for which we want the precipitates distribution. Default is 0.
n_samples (int) – Not implemented yet - The number of “snapshots” of the precipitates distribution we want.

log¶

The standard output passed by PreciSo during its execution.

Type: str

distribution¶

A preciso.Distribution object, that contains all the data related to precipitates size distributions.

Type: preciso.Distribution object

precipitatiton¶

A nested dictionary that contains the data in the form of pandas dataframes.

Type: dict

mechanics¶: A nested dictionary that contains the data in the form of pandas dataframes.

parse_log()¶

Opens and reads the log.log file.

Parameters: results_directory (str or pathlib.Path object) – The location of the results files created by PreciSo.
Returns: log (str) – The content of log.log

parse_mechanics(results_directory)¶

Opens and reads the “mechanics” files saved by Preciso.

Parameters

input_file (str or pathlib.Path object) – The location of the input file to search in.
results_directory (str or pathlib.Path object) – The location of the results files created by PreciSo.

Returns

results (dict) – A nested dictionary that contains the data in the form of pandas dataframes.

parse_precipitation(results_directory)¶

Opens and reads the “results” files saved by Preciso.

Parameters

input_file (str or pathlib.Path object) – The location of the input file to search in.
results_directory (str or pathlib.Path object) – The location of the results files created by PreciSo.

Returns

results (dict) – A nested dictionary that contains the data in the form of pandas dataframes.

preciso.results.keyword_to_value(input_file, keyword, index, multiple=False, strict=True)¶

Returns the value associated to given keyword in a Preciso InputFile.

Parameters

input_file (str or pathlib.Path object) – The location of the input file to search in.
keyword (str) – The keyword you’re looking for the value of.
index (int) – The position of the value in the line. For example with key foo val, val is at position [2] on the line.
multiple (bool) – Allow multiple occurences of the keyword to be found.
strict (bool) – Raise an error if no match was found. If False, [] is returned instead.

Returns

values (list of str) – The values found.

preciso.run¶

preciso.run.run_input_file(inputFileName, nodes, n_samples, write_limit=100, debug=False)¶

A tool to run PreciSo with a specified inputFile as input. It makes use of a system call to the PreciSo executable. The input file should be formatted as described here 1. PreciSo binaries are treated as package data 2 and are therefore accessible using the pkg_ressources module. System calls are made using subprocess.getoutput 3.

1: https://framagit.org/arnall/preciso/wikis/Input%20files%20in%20PreciSo
2: https://docs.python.org/3/distutils/setupscript.html#installing-package-data
3: https://docs.python.org/3/library/subprocess.html#subprocess.getoutput

Parameters

inputFileName (pathlib.Path object or str) – The path to the input file to use in Preciso. Can be given either as a pathlib.Path object (recommended as it is cross-plateform) or as a str that complies with the computer’s filesystem.
nodes (List of int (optional)) – The id of the node(s) for which we want the precipitates distribution. Default is [0].
n_samples (int) – The number of images of the precipitate distribution that should be saved.
write_limit (int) – The maximum total size of the files written by PreciSo, in Megabytes. It prevents PreciSo from filling up your computer’s hard drive. Default value is 100MB. If write_limit is of a type different than int, no limit is set. Windows is not supported, there will be no limit on this plateform.
debug (boolean) – Whether you want to print PreciSo’s output directly to the terminal, e.g. to spot situations when it’s stuck and can’t converge. Default is False.

Returns

out (Results obj) – The results of the simulation, in the form of a Results object.

Examples

>>> import preciso.run
>>> preciso.run.run_input_file('')
Welcome to PreciSo v3.0
FATAL ERROR: PreciSo have been launch with an incorrect number of arguments

preciso.HDF5¶

preciso.HDF5.HDF5_make(title, inputFileName, res=None, target_path=None, mode=None, temp=True, write_limit=100, nodes=None, n_samples=2, debug=False)¶

Procedure creating an hdf data file for preciso results

Parameters

title (str) – The name of the created file. Make sure its extentsion is ‘.hdf5’.
inputFileName (str or Pathlib.Path) – The location of the input file used for the simulation. The file information will be stored into the hdf created, so that the file itself can be discarded afterwards.
res (Results object) – The results of the precio simulation with the specified arguments. By default, the function is running a a standalone, and determine this object calling preciso by itself.
target_path (str or Pathlib.Path) – The directory where the HDF5 file will be saved. Default is current directory.
mode (char) – The opening mode for the HDF5 file. Default is ‘x’ to prevent overwriting existing data; use ‘w’ to bypass.
temp (bool) – If True (default), PreciSo will run in a temporary folder, and its results files will be read and outputed. All files will be discarded at the end. If false, run_input_file is directly called and output files will be created in current working directory.
write_limit (int) – The maximum size of the files written by PreciSo, in Megabytes. It prevents PreciSo from filling up your computer’s hard drive. Default value is 100MB. If write_limit is of a type different than int, no limit is set. Windows is not supported, there will be no limit on this plateform.
nodes (List of int (optional)) – The id of the node(s) for which we want the precipitates distribution. Default is [0].