Python API — PreciSo documentation

# Python API

Below is the automatically generated documentation of PreciSo.

## preciso

`preciso.preciso.` `add_logo`(f, x_frac, y_frac, scale=1, alpha=1, path='', dpi=300)

  Add an image to the figure (not the axes)

  Parameters

    - f – a matplotlib figure instance.

    - 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. Defalut is 1.

    - alpha – Sets the opacity (named alpha in matplotlib). Must be a float between 0 and 1. Default is 1 (full opacity).

    - path – The path to the image to add to the figure, as a string or a pathlib.Path object. By default, it adds the PreciSo logo image that is included in the python package.

    - dpi – Set the figure resolution in dpi (dots per inch). Default is 300.

  Examples

  To insert a preciso logo at the center of the figure, at half it’s original size, with 15% opacity.

      >>> import preciso
      >>> import matplotlib.pyplot as plt
      >>> f = plt.Figure()
      >>> f = add_logo(f, x_frac=0.5, y_frac=0.5, scale=0.5, alpha=0.15)

`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.` `logo_path`()

  Returns the path to the PreciSo logo as a pathlib.Path object.

`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.preciso.` `version`()

  Finds the installed version of PreciSo using pkg_resources.

  Examples

      >>> import preciso
      >>> preciso.version()
      '0.1.2'

## 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].