Welcome to symtolerance’s documentation!

Introduction

For an introduction about how to perform a tolerance analysis, see the documentation of the symtolerance2.symtol.SymTol class.

Modules

symtolerance2.symtol

class symtolerance2.symtol.SymTol(sym_project)[source]

The SymTol class is used to perform a tolerance analysis based on an existing SyMSpace project.

Note

Tolerance analysis has pre-alpha status and is not integrated into the SyMSpace core and not accessible via GUI interaction. Setting up and running ana analysis has to be done using the SyMSpace Python Console. No automatic postprocessing is available at the moment!

Note

In this introductory documentation the most common and necessary steps to perform a tolerance analysis are described. This is not a full documentation of all features. More details might be presented at the available methods.

Basic workflow

_images/workflow.png
Initialization
Starting from an existing SyMSpace project, this base project has to be prepared for tolerance analysis, i.e., define which fields are affected by tolerances, what the tolerance distribution looks like, and what the results are to be investigated during analysis. This SyMSpace project can then be used to initialize a SyMSpace tolerance analysis.
Configuration
Before starting an analysis, several settings can be modified. For example, number of simulation, number of indizes of the temporary SyMSpace project which is later created for simulation, autosave interval, …
Start an analysis
If an analysis is started, a temporary SyMSpace project is created based on the initialization project. This temporary project gets a certain number of indizes, which can be defined in the configuration of the tolerance analysis problem. Then, tolerance affected values are assigned to each index and all indizes are regenerated. If an index is finnished sucessfully, variables and results are collected, new tolerance affected values are assigned, and the corresponding index is regenerated. This loop runs, until a predefined number of tolerance affected evaluations is finnished
Clean up
At the end, a clean up can be performed to remove the temporary project. This has to be triggered manually!

Definition of tolerance-affected variables

Tolerances can be defined in the Comment box of the respective parameter which can be found in the Details-tab of the SyMSpace GUI. The comment has to start with the @Tolerance string, further details are defined as json string. For example, a variable whichs’ value has uniform distribution can be defined writing

@Tolerance{"var":{"uniform":{"lower_tol":-0.1, "upper_tol":0.7}}}

in the Comment area of the corresponding SyMSpace parameter. The key "var" defines that this parameter is a variable which has to be modified during tolerance analysis. For a list of available distributions see _findAtToleranceData_r().

Definition of results

Results which have to be observed during tolerance analysis are defined in a similar manner, using the "res" keyword:

@Tolerance{"res":{}}

For more information, also see _findAtToleranceData_r().

Running an analysis

When the SyMSpace project is prepared for tolerance analysis (setting variables and results), assign the CurProject handle to the SyMSpace Python Console (Debug ‣ Python ‣ Assign Project Handle in Python Console, strg + P). Then initialize the tolerance project in the SyMSpace Python Console(for other initialization methos see __init__()).

>>> stp = SymTol(CurProject)                            # create a SymTolProject

After creation of a SymTol instance, different settings can be defined (for more information, see the symspace.symtolerance2.symtolsettings module). The SymTol object has a config attribute, where all settings can be defined. Some useful configurations might be:

>>> stp.config.samplesCount = 100                       # number of samples to be evaluated
>>> stp.config.simProject.indices = 20                  # number of indizes of the temporary SyMSpace project
>>> stp.config.simControl.tolDataPickleInterval = 10    # autosave functionality (variables and results are
>>>                                                     # saved after n evaluated samples, overwriting
>>>                                                     # previouse autosave files)

After adopting the settings, one can start a tolerance analysis using

>>> stp.start()

Now 100 samples are evaluated, where every sample is automatically defined randomly with the specified distribution as defined by the @Tolerance{} key.

Note

Unfortunately, Python threading seems not to be possible from the SyMSpace Python Console. Thus, during performing the tolerance analysis the SyMSpace Python Console is locked. If you want to interrupt the evaluation of the analysis - might be helpful especially during testing phase - a workaround using a simulation control file <SyM-project-filename>.ctrl is created. This file has two flags defined, namely stop=False and finish=False. Set either of these to True and save the file to stop or finish the analysis before the defined number of evaluations is reached. When setting finish to True, all indizes which are already under progress are finished. setting stop to True, the analysis is stopped imediatly and all running jobs are removed.

When the defined number of samples is evaluated successfully, the results and also the corresponding variables can accessed via the results and variables attributes of the SymTol object.

>>> stp.results
>>> stp.variables

Both, results and variables, are stored in a 3-dimensional numpy array, where the different samples can be accessed via the 3rd dimension (axis=2). The variable and result data of a single sample can be 2-dimensional and is stored in axis=0 and axis=1.

If additional samples are necessary, the analysis can be started as often as necessary. Results and variables are appended to the existing data.

Note

If a tolerance analysis is initialized from a project where an existing analysis is available, these data can be loaded and the analysis can be continued.

Warning

If the analysis should not be continued, but a new analysis should be performed, the axisting tolerance-data file will be overwritten. If you want to keep this data, make a copy of the original file under a different name!

Clean-up tolerance analysis project

Before you close the SyMSpace - Python Console, a clean-up can be performed. This removes all temporary files created during the tolerance analysis.

>>> stp.cleanup()

Post-processing

For postprocessing of scalar objectives the symtolerance2.toldata.TolData class can be used. But postprocessing is not integrated into the main workflow so far and the symtolerance2.toldata.TolData class has pre-alpha status!

Methods

__init__(sym_project) SymTol initialization function.
cleanUpProject() Cleans up the SyMSpace project which is cereated for temporary use of tolerance analysis.
createSimProject() Create and prepare the SyMSpace project which will be used for tolerance analyses.
extractTolDataProject(index) Duplicate the <SymTol>.baseProject and set the tolerance variables to a selected set out of the calculated variations.
findAtToleranceData()
getResultValues([sym_project, insert_pos]) Collect all tolerance related results from the current index of the SyMSpace - project sym_project and inserts these at position insert_pos to the results.
getVariableValues([sym_project, insert_pos]) Collect all tolerance related variables from the current index of the SyMSpace - project sym_project and inserts these at position insert_pos to the variables.
getWorstCaseIndex() Evaluate the index where the worst case design is stored within the results() and variables() properties of the SymTol instance.
loadTolData([fname]) Load variables and results from previous tolerance analysis, stored by pickleTolData().
pickleSimIndex([fname]) Automatically pickle the whole SyMSpace tree of the current index of the simulation project.
pickleTolData([fname]) Automatically pickle tolerance-affected data, i.e., results and variables.
printAtToleranceData() Print all tolerance related data found in SyMSpace project (identified by the @Tolerance{} keyword in the Comment:__________ field).
setBaseValues() sets the nominal values to the actual index of the (temporary) SyMSpace project used for tolerance analysis
setTolerancesVariables([regenerate]) Set values to the tolerance affected variables as defined in the Comment:________ area of the corresponding field in the SyMSpace tree using the keyword @Tolerance{"var":{}}.
start([samplesCount]) Start tolerance analysis.
startNominalSet() Run the nominal SyMSpace model without tolerances applied to the respective parameters.

Attributes

config Access all configuration settings available for tolerance analysis.
results Get all results of the tolerance analysis, i.e., values of all SyMSpace parameters which are marked with @Tolerance{"res":{}} in the parameters’ Comments:________ area.
sampleCount Get the number of tolerance-affected samples available in the project.
variables Get all variables of the tolerance analysis, i.e., values of all SyMSpace parameters which are marked with @Tolerance{"var":{}} in the parameters’ Comments:________ area.

Details

__init__(sym_project)[source]

SymTol initialization function.

Parameters:sym_project (symspace.wrapper.symwrapper.SymProject | str (absolute path to mop file)) – Assign a SymProject handle from the symspace.wrapper.symwrapper module OR the absolute path to the .mop file of the SyMSpace project which should be loaded.
cleanUpProject()[source]

Cleans up the SyMSpace project which is cereated for temporary use of tolerance analysis. If original SyMSpace project is used, all indices are removed (except first one)

config

Access all configuration settings available for tolerance analysis.

Returns:Data class holding all configuration settings. For more information about available settings see the symtolerance2.symtolsettings.SymTolSettings documentation.
Return type:symtolerance2.symtolsettings.SymTolSettings
createSimProject()[source]

Create and prepare the SyMSpace project which will be used for tolerance analyses. By default the original SyMSpace project is cloned and stored as <SyMProject_name>_tol.mop. If the original SyMSpace project shall be used, what is not recommended, set

<SymTol>.config.simProject.clone=False

The (temporary) simulation project can be removed using cleanUpProject().

Note

If a SyMSpace formula is set to be tolerance affected, the formula is converted to a ParamField during creation of the (temporary) simulation project (a formula field can be useful to define nominal values for vectors or matrices). If a tolerance affected SyMSpace field has its constant flag set, this is removed during creation of the simulation project.

extractTolDataProject(index)[source]

Duplicate the <SymTol>.baseProject and set the tolerance variables to a selected set out of the calculated variations. The set is defined by the index it is stored in the results() and variables() properties (3rd dimension, e.g., <SymTol>.variables[:,:,index] values are assigned to new project).

The new SyMSpace project is stored as <SyMProject_name>_tolData_idx<index>.mop.

Note: The function getWorstCaseIndex() can be used to determine the index leading to the worst case with respect to a certain results parameter.

Parameters:index (int) – <SymTol>.variables[:,:,index] values are assigned to new project
findAtToleranceData()[source]
getResultValues(sym_project=None, insert_pos=None)[source]

Collect all tolerance related results from the current index of the SyMSpace - project sym_project and inserts these at position insert_pos to the results. Definition of sym_project and insert_pos is mainly to add nominal results at position (:,:,0).

Parameters:
  • sym_project (symspace.wrapper.symwrapper.SymProject) – SyMSpace project where results are collected from, default is simulation project (attr:<SymTol>.simProject)
  • insert_pos (int) – position (of axis 2/ 3rd dimension) in results where values are inserted, default is appending at the end.
getVariableValues(sym_project=None, insert_pos=None)[source]

Collect all tolerance related variables from the current index of the SyMSpace - project sym_project and inserts these at position insert_pos to the variables. Definition of sym_project and insert_pos is mainly to add nominal results at position (:,:,0).

Parameters:
  • sym_project (symspace.wrapper.symwrapper.SymProject) – SyMSpace project where results are collected from, default is simulation project (attr:<SymTol>.simProject)
  • insert_pos (int) – position (of axis 2/ 3rd dimension) in variables where values are inserted, default is appending at the end.
getWorstCaseIndex()[source]

Evaluate the index where the worst case design is stored within the results() and variables() properties of the SymTol instance. The worst case design is evaluated for each result (objective) and is based on the available data (it is not the global worst case configuration!!)

Returns:dict['SymIdentifier'] = <worst case index> with respect to the SyMSpace field defined by code:<’SymIdentifier’>
Return type:dict
loadTolData(fname=None)[source]

Load variables and results from previous tolerance analysis, stored by pickleTolData().

Parameters:fname (str) – full path to pickle file stored by the pickleTolData() function; if default (None), default file name from pickleTolData() is used.
pickleSimIndex(fname=None)[source]

Automatically pickle the whole SyMSpace tree of the current index of the simulation project.

If field data is array, struct, … it is stored as serialized pickle string and has to be loaded using

pickle.loads(base64.b64decode(<serialized string>))
Parameters:fname (str) – full path of the pickle file, if not defined, project path and name with time code is used!
pickleTolData(fname=None)[source]

Automatically pickle tolerance-affected data, i.e., results and variables. Default filename is the name of the SyMSpace-project with _TolData appended (<SyM_project_name>_TolData.p).

Parameters:fname (str) – full path of the pickle file, if not defined, project path and name with _TolData suffix is used!
Returns:dictionary with keys 'results' and 'variables', holding the data returned by results and variables respectively.
Return type:dict
printAtToleranceData()[source]

Print all tolerance related data found in SyMSpace project (identified by the @Tolerance{} keyword in the Comment:__________ field).

results

Get all results of the tolerance analysis, i.e., values of all SyMSpace parameters which are marked with @Tolerance{"res":{}} in the parameters’ Comments:________ area. The results of a certain parameter can be accessed from this results dictionary via its SyMSpace identifier (key). The data itself is stored as 3-dimensional numpy.ndarray, where the different tolerance affected samples are stored in the 3rd dimension (axis=2). Values of the nominal dataset are, if available, at index (:,:,0). The variable set leading to a certain result (certain index in 3rd dimension) can be accessed via variables().

Note

So far, only 2-dimensional data \(\in \mathbb{R}^{2}\) can be processed as results of a tolerance analysis

Returns:Dictionary where keys correspond to SyMSpace identifier of the result fields and values are of type numpy.ndarray, holding tolerance information in the third axes. Values of the nominal dataset are, if available, at index (:,:,0).
Return type:dict
sampleCount

Get the number of tolerance-affected samples available in the project. If the nominal problem is calculated (startNominalSet()), this is included in the sample count value.

Returns:Number of samples available in the project
Return type:int
setBaseValues()[source]

sets the nominal values to the actual index of the (temporary) SyMSpace project used for tolerance analysis

setTolerancesVariables(regenerate=False)[source]

Set values to the tolerance affected variables as defined in the Comment:________ area of the corresponding field in the SyMSpace tree using the keyword @Tolerance{"var":{}}.

The general structure of the comment-string to define a tolerance affected variable is:

@Tolerance{"var":{"<distribution>":{["<setting>":<value>]}}}

Available distributions are:

“<distribution>” [“<setting>”:<value>] Comment
"uniform" "lower_tol":<float>,"upper_tol":<float>, uniform distribution with lower and upper boundary; lower_tol has to be defined with negative sign.
"norm" "sigma":<float> normal (Gauss) distribution with standard deviation sigma

For example, a parameter that has a tolerance range of [-0.1,0.15] with uniform distribution, the comment (json) string looks:

@Tolerance{"var":{"uniform":{"lower_tol":-0.1, "upper_tol":0.15}}}

Note

As nominal value, the field value (Data) of the corresponding SyMSpace parameter is used.

Parameters:regenerate (bool) – if set to True, SyMSpace project is regenerated after assigning new toelrance parameters, default False
start(samplesCount=None)[source]

Start tolerance analysis. Tolerance variables and results can be accessed via variables and results. Check if <SymTol>.config.simControl.indexTimeout and other simControl settings are defined properly!

Parameters:samplesCount (int | None) – Parameter can be used to override <SymTol>.config.samplesCount value.
startNominalSet()[source]

Run the nominal SyMSpace model without tolerances applied to the respective parameters. If the status of index 0 of the base Project is OK (i.e., not incomplete nor error), values from this index will be used as nominal set. Otherwise, index 0 of the simulation project (:attr:<SymTol>.simProject`) is set to nominal values and calculated!

Nominal values are stored at index 0 of :attr:results` and variables and pickled SyMSpace tree is stored with filename 0_nominal.p in the common store directory (<>.tol.files).

variables

Get all variables of the tolerance analysis, i.e., values of all SyMSpace parameters which are marked with @Tolerance{"var":{}} in the parameters’ Comments:________ area. The values of a certain parameter can be accessed from this results dictionary via its SyMSpace identifier (key). The data itself is stored as 3-dimensional numpy.ndarray, where the tolerance affected variable values are stored in the 3rd dimension (axis=2). The nominal values are, if available, at index (:,:,0). The results caused by a certain tolerance setting (certain index in 3rd dimension) can be accessed via results().

Note

So far, only 2-dimensional data \(\in \mathbb{R}^{2}\) can be processed as variables of a tolerance analysis.

Returns:Dictionary where keys correspond to SyMSpace identifier of the variable fields and values are of type numpy.ndarray, holding tolerance information in the third axes. Values of the nominal dataset are, if available, at index (:,:,0).
Return type:dict

symtolerance2.symtolsettings

class symtolerance2.symtolsettings.SimControlSettings(remoteCompute: bool = True, optimize: bool = True, runSim: bool = True, batch: int = 5, indexTimeout: int = 120, jobTimeout: int = 0, tolDataPickleInterval: int = 0) → None[source]

Settings used to control processing of the indices and JobManager related information

class symtolerance2.symtolsettings.SimProjectSettings(clone: bool = True, cleanUp: bool = True, indices: int = 20, initializeIndices: bool = True) → None[source]

Settings to control the SyMSpace project which is used during tolerance calculation

class symtolerance2.symtolsettings.SymTolSettings(baseProjectFile: str, samplesCount: int = 500, storeIndices: bool = False, storeIndicesDirectory: str = None, simProject: symtolerance2.symtolsettings.SimProjectSettings = SimProjectSettings(clone=True, cleanUp=True, indices=20, initializeIndices=True), simControl: symtolerance2.symtolsettings.SimControlSettings = SimControlSettings(remoteCompute=True, optimize=True, runSim=True, batch=5, indexTimeout=120, jobTimeout=0, tolDataPickleInterval=0)) → None[source]

Main settings class to handle configurations of symtol.SymTol class

symtolerance2.toldata

class symtolerance2.toldata.TolData(data, label=None)[source]

Class to process statistic data

Warning

This class is under heavy construction and not consistently documented so far. No standardized way of using this class for postprocessing tolerance data or using it for creation of a online stop criterion for tolerance analysis is defined so far!

Methods

__init__(data[, label]) Initialize self.
fit_gauss() fit gauss (norm) distribution to self.data
fit_kde() fits a probability density function to self.data using kernel density estimation as implemented in the scipy.stats module .
get_F(quantile_val[, method])
get_cdf_diff(x_lst, cdf_lst[, area])
get_cdf_diff_area(x_lst, cdf_lst)
get_dkw_conf_quantiles([p, alpha, method])
get_dkw_conf_set([method, alpha]) Modified version from https://www.statsmodels.org/dev/_modules/statsmodels/distributions/empirical_distribution.html
get_dkw_epsilon(nobs, alpha) Dvoretzky - Kiefer - Wolfowitz confidence value
get_ecdf() calculate the empiric cumulative distribution function (ECDF) \(\widehat{F}\) of the available data.
get_fit_data([method, fit_q, q_steps, verbose]) calculate probability density function (PDF) and cumulative distribution function (CDF) based on fitted distribution.
get_quantile(cdf_val[, method])
get_quantile_from_data(x, F, p)
get_slope([p0, p1])
get_worst_case() get the worst case value and its index within the data attribute of the TolData class.
plot_cdf([method, xlabel, ylabel, …]) Plot the cumulative distribution function of the underlying data TolData.data using matplotlib.
run_batch_test([split, tests])
run_batch_test_conf([confidence, split, tests])
update_data(data) overwrite previous data

Attributes

Details

__init__(data, label=None)[source]

Initialize self. See help(type(self)) for accurate signature.

fit_gauss()[source]

fit gauss (norm) distribution to self.data

Returns:(mu,std)
Return type:mean and standard deviation of fitted normal distribution
fit_kde()[source]

fits a probability density function to self.data using kernel density estimation as implemented in the scipy.stats module . This uses a Gaussian kernel and Scott’s Rule (of thumb) for bandwidth selection.

Returns:kernel
Return type:scipy.stats.gaussian_kde object
get_F(quantile_val, method='kde')[source]
static get_cdf_diff(x_lst, cdf_lst, area=True)[source]
static get_cdf_diff_area(x_lst, cdf_lst)[source]
get_dkw_conf_quantiles(p=0.95, alpha=0.05, method='gauss_kde')[source]
get_dkw_conf_set(method='empiric', alpha=0.05)[source]

Modified version from https://www.statsmodels.org/dev/_modules/statsmodels/distributions/empirical_distribution.html

Constructs a Dvoretzky-Kiefer-Wolfowitz confidence band for the eCDF.

Parameters:
  • F (array_like) – The empirical distributions
  • alpha (float) – Set alpha for a (1 - alpha) % confidence band, p=(1-alpha)

Notes

Based on the DKW inequality.

\[P \left( \sup_x \left| F(x) - \hat(F)_n(X) \right| > \epsilon \right) \leq 2e^{-2n\epsilon^2}\]

References

Wasserman, L. 2006. All of Nonparametric Statistics. Springer.

static get_dkw_epsilon(nobs, alpha)[source]

Dvoretzky - Kiefer - Wolfowitz confidence value

Parameters:
  • nobs
  • alpha – float Set alpha for a (1 - alpha) % confidence band.
Returns:

epsilon

get_ecdf()[source]

calculate the empiric cumulative distribution function (ECDF) \(\widehat{F}\) of the available data.

Returns:(ecdf_q, ecdf) quantile values ecdf_q and corresponding probability values ecdf of available data
Return type:(np.ndarray, np.ndarray)
get_fit_data(method='kde', fit_q=None, q_steps=100, verbose=1)[source]

calculate probability density function (PDF) and cumulative distribution function (CDF) based on fitted distribution.

Parameters:
  • method (str) – method which is used to fit the distribution [‘gauss’,’kde’], default ‘kde’
  • fit_q (array_like or None) – quantile values where PDF/CDF shall be evaluated, default ‘None’ –> automatic definition
  • q_steps (int) – if fit_q==None, quantile range is chosen based on the available data and divided into q_steps steps
  • verbose (int) – if verbose>0, info message can be printed, default 1
get_quantile(cdf_val, method='kde')[source]
static get_quantile_from_data(x, F, p)[source]
get_slope(p0=0.2, p1=0.8)[source]
get_worst_case()[source]

get the worst case value and its index within the data attribute of the TolData class.

Returns:(index, value) of worst case entity
Return type:(int, float)
plot_cdf(method=('ecdf', 'kde'), xlabel=None, ylabel='CDF', nominal_line=False, ax=None, **plotargs)[source]

Plot the cumulative distribution function of the underlying data TolData.data using matplotlib.

Parameters:
  • method (array-like) – define the method which is used to evaluate the CDF. Possible values are ‘ecdf’ to plot the empiric cumulative distribution function or one of the methods available in the get_fit_data() method. Default is (‘ecdf’, ‘kde’)
  • xlabel (str) – define custom xlabel, default None. If default and TolData.label is defined, this label is used.
  • ylabel (str) – define custom ylabel, default 'CDF'
  • ax (matplotlib.axes) – define axes handle to force plotting to a certain axes
  • plotargs – kwargs forwarded to matplotlib.axes.plot() function
Returns:

handle to matplotlib axes for further customization

Return type:

matplotlib.axes

Examples

import numpy as np
from symtolerance2.toldata import TolData
import matplotlib.pyplot as plt

# create normal distributed random values
data = np.random.normal(size=100)
td = TolData(data, label='random values')

td.plot_cdf()

(Source code, png, hires.png, pdf)

_images/index-1.png
run_batch_test(split=0.99, tests=1000)[source]
run_batch_test_conf(confidence=0.9, split=0.99, tests=1000)[source]
update_data(data)[source]

overwrite previous data