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
- 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 ( , + ). 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 thesymspace.symtolerance2.symtolsettings
module). TheSymTol
object has aconfig
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, namelystop=False
andfinish=False
. Set either of these toTrue
and save the file to stop or finish the analysis before the defined number of evaluations is reached. When settingfinish
toTrue
, all indizes which are already under progress are finished. settingstop
toTrue
, 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
andvariables
attributes of theSymTol
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 thesymtolerance2.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()
andvariables()
properties of theSymTol
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
andvariables
.printAtToleranceData
()Print all tolerance related data found in SyMSpace project (identified by the @Tolerance{}
keyword in the 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 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’ 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’ area.Details
-
__init__
(sym_project)[source]¶ SymTol
initialization function.Parameters: sym_project ( symspace.wrapper.symwrapper.SymProject
| str (absolute path to mop file)) – Assign aSymProject
handle from thesymspace.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 theresults()
andvariables()
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
-
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.
- sym_project (
-
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.
- sym_project (
-
getWorstCaseIndex
()[source]¶ Evaluate the index where the worst case design is stored within the
results()
andvariables()
properties of theSymTol
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 frompickleTolData()
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
andvariables
. 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 byresults
andvariables
respectively.Return type: dict
-
printAtToleranceData
()[source]¶ Print all tolerance related data found in SyMSpace project (identified by the
@Tolerance{}
keyword in the 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’ 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 viavariables()
.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
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
andresults
. Check if<SymTol>.config.simControl.indexTimeout
and othersimControl
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 filename0_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’ 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 viaresults()
.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 theTolData
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
-
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_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_worst_case
()[source]¶ get the worst case value and its index within the
data
attribute of theTolData
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 andTolData.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)
- 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
-