# OptiPRISMS  [](https://pypi.org/project/OptiPRISMS/) 
Perform inverse analysis to retrieve Crystal Plasticity parameters used for CPFEM simulation through the PRISMS-Plasticity software [[1]](#prisms). This inverse analysis is done using data from in situ tensile tests and Scanning Electron Microscopy Digital Image Correlation (SEM-DIC).
## How it works
This program will optimize CP parameters in order to minimize a given cost function.
At each step of the optimization process, it will:
1. generate configuration files for PRISMS-Plasticity;
2. run PRISMS-Plasticity from these files;
3. read results and compare them against experimental data;
4. return a cost function, evidencing *how far* the simulation is, compared to the experiment,
5. remove simulation files.
In order to generate the PRISMS configuration files, this software will parse *template* files in order to retrieve which parameters it shall optimize.
Records for each optimization loop will be stored in a log file, so that the user can track the evolution of optimized parameters and cost functions. In addition, OptiPRISMS will use this file to avoid reruning preexisting simulations, so that the optimization can be stopped then resumed.
Full description of the algorithm is provided in [[2]](#paper).
## Required materials
- The mesh of the microstructure (in .msh format). One can use [MTEX2Gmsh](https://github.com/DorianDepriester/MTEX2Gmsh/blob/master/MTEX2prisms/MTEX2PRISMS.pdf) [[3]](#mtex2gmsh) to generate a conforming mesh directly from EBSD data.
- [PRISMS-Plasticity software](https://github.com/prisms-center/plasticity).
- Python 3.6 (or later) with the following modules: numpy, scipy, vtk, pandas and optimparallel (optional).
- Experimental data, consisting in:
- a macroscopic tensile curve (strain-stress values as a CSV file),
- SEM-DIC displacement measurements, stored as individual CSV files named sequentially (eg. "DIC_1.csv", "DIC_2.csv" and so on).
Each of these files must have tabular data, ordered this way:
1. x coordinates of DIC points where DIC measurements are performed,
2. y coordinates of DIC points where DIC measurements are performed,
3. x displacements,
4. y displacements,
5. correlation coefficients (optional, see [Cost Function](#cost-function) section)
## Cite this project
If you use this project, please cite ref. [[2]](#paper). You can use the following BibTeX entry:
```bibtex
@article{OptiPRISMS,
title = {Crystal Plasticity simulations of in situ tensile tests: A two-step inverse method for identification of CP parameters, and assessment of CPFEM capabilities},
journal = {International Journal of Plasticity},
pages = {103695},
year = {2023},
issn = {0749-6419},
doi = {https://doi.org/10.1016/j.ijplas.2023.103695},
url = {https://www.sciencedirect.com/science/article/pii/S074964192300181X},
author = {D. Depriester and J.P. Goulmy and L. Barrallier},
}
```
## Installation
You can install the latest release of OptiPRISMS with pip:
```bash
pip install OptiPRISMS
```
Otherwise, you can install the development version from sources:
```bash
git clone https://github.com/DorianDepriester/OptiPRISMS.git
cd OptiPRISMS
pip install --editable .
```
## Step-by-step method to run optimization
1. Create template files. They consist in usual configuration files (see [here](https://github.com/prisms-center/plasticity/blob/master/docs/PRISMS_plasticity_user_manual_V1_4_0.pdf) for details), where every value you want to optimize is given a variable name. These names must be precessed by a dollar symbol (``$``, e.g. ``$a`` instead of ``a``).
2. Edit the configuration file to tune optimization-related parameters (see below for details or check out the [example](https://github.com/DorianDepriester/OptiPRISMS/tree/main/example) folder).
3. With Python3, run the `optimize` function from `OptiPRISMS` module. E.g.:
```python
from OptiPRISMS import optimize
res = optimize(config_file='myConfigFile.ini')
```
4. Then, wait a couple of days (or weeks...).
In the meantime, you can track the progress of optimization by having a look on the [log file](#log-file).
## Configuration file
This file describes locations of data and parameters for optimization. It divides in sections (some of them are mandatory, other are not).
See full examples in [example](example) folder.
### Mandatory sections
#### [Initial Guess]
Provide here starting values for the variables you want to optimize. The variables names must be consistent with these in templates for PRISMS parameter files (as detailed [here](#step-by-step-method-to-run-optimization)).
#### [Bounds]
- **lower**: list of lower bounds
- **upper**: list of upper bounds
#### [PRISMS]
- **prm file**: path to the main parameter file template
- **latent hardening ratio** : path to latent hardening ratio template
- **path to prisms**: path to PRISMS-Plasticity executable file. This entry is not required if Slurm is used (see [\[Slurm\]] section).
#### [Experimental Data]
- **DIC data**: pattern describing the path to CSV files with DIC measurements (without step number nor extension).
OptiPRISMS will automatically append the step number and the CSV extension to this pattern. For instance,
if one wants to use files ``DIC_1.csv`` and ``DIC_2.csv``, this parameter should be
set to ``DIC_``.
- **DIC time steps** *(optional)*: increment numbers corresponding to each step of DIC measurements.
If not set, they will be inferred from option `set Tabular Time Output Table` in prm file.
- **tensile curve**: path to strain-stress values of tensile curve
- **tensile direction** *(optional)*: Direction of measured stress and strain. It can be ``x`` or ``y``.
The default value is ``x``.
#### [Cost Function]
- **weight on tensile curve**: weight to apply to the tensile curve in the overall cost function
- **penalty**: penalty value to raise if the simulation fails
- **weight by correlation coefficients**: if enabled, the kinematic cost function will weight the
displacement errors by the inverse of the correlation coefficients. The latter will
be read from the 6th column of the DIC CSV files (as detailed in [Required Materials](#required-materials) section)
#### [Log File]
- **file path**: path to log file
### Optional sections
#### [Minimize]
Pass here any optional parameter(s) for the ``options`` argument of `scipy.optimize.minimize`. See [the options for ``scipy.optimize.minimize`` with L-BFGS-B method for available arguments](https://docs.scipy.org/doc/scipy/reference/optimize.minimize-lbfgsb.html#optimize-minimize-lbfgsb).
#### [Minimize parallel]
This section allows to use a parallel implementation of the L-BFGS-B minimizer [[3]](#optim_parallel), through the ``minimize_parallel`` function (from [``optimparallel``](https://github.com/florafauna/optimParallel-python) module).
- **use parallel minimizer**: whether to use `minimize_parallel`, instead of `scipy.optimize.minimize` (default is No)
In addition, any keyword argument normally passed to the `parallel` option of `minimize_parallel` can be defined in this section. See [the related documentation](https://github.com/florafauna/optimParallel-python/blob/8bf622be1431ba10fef1d795521a2b1d86307c9d/src/optimparallel.py#L170) for available options.
#### [Slurm]
- **use Slurm**: whether to use the Slurm workload manager. Default is No.
- **batch file**: path to batch file to use for submitting a job running PRISMS-Plasticity. The path to the prm file will be passed as the first argument of this script.
#### [Debug]
- **fake simulations**: If Yes, each simulation is not computed. The related commands are printed instead. Default is No.
- **fake deletions**: Turn off automatic removal of simulation results (step 5 in [How it works](#how-it-works) section). Default is No.
## References
<a id="prisms">[1]</a> Yaghoobi et al., (2019). Prisms-plasticity: An open-source crystal plasticity finite element software. Computational Materials Science, 169:109078, https://doi.org/10.1016/j.commatsci.2019.109078
<a id="paper">[2]</a> Depriester et al., (2023). Crystal Plasticity Simulations of in Situ Tensile Tests: A Two-Step Inverse Method for Identification of CP Parameters, and Assessment of CPFEM Capabilities. International Journal of Plasticity, https://doi.org/10.1016/j.ijplas.2023.103695
<a id="mtex2gmsh">[3]</a> Depriester et al., (2020). MTEX2Gmsh: a tool for generating 2D meshes from EBSD data. Journal of Open Source Software, 5(52):2094, https://doi.org/10.21105/joss.02094
<a id="optim_parallel">[4]</a> Gerber, F. and Furrer, R. (2019). optimParallel: An R package providing a parallel version of the L-BFGS-B optimization method, The R Journal, 11(1):352–358, http://doi.org/10.32614/RJ-2019-030
Raw data
{
"_id": null,
"home_page": "https://github.com/DorianDepriester/OptiPRISMS",
"name": "OptiPRISMS",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Dorian Depriester",
"author_email": "dorian.depriester@ensam.eu",
"download_url": "https://files.pythonhosted.org/packages/a8/fa/2322fc0ccf54e840a8c4dfa5797771939348ca76c3e48bb4476424c357a2/OptiPRISMS-1.1.1.tar.gz",
"platform": null,
"description": "# OptiPRISMS  [](https://pypi.org/project/OptiPRISMS/) \n\nPerform inverse analysis to retrieve Crystal Plasticity parameters used for CPFEM simulation through the PRISMS-Plasticity software [[1]](#prisms). This inverse analysis is done using data from in situ tensile tests and Scanning Electron Microscopy Digital Image Correlation (SEM-DIC).\n\n## How it works\n\nThis program will optimize CP parameters in order to minimize a given cost function.\nAt each step of the optimization process, it will:\n\n1. generate configuration files for PRISMS-Plasticity;\n2. run PRISMS-Plasticity from these files;\n3. read results and compare them against experimental data;\n4. return a cost function, evidencing *how far* the simulation is, compared to the experiment,\n5. remove simulation files.\n\nIn order to generate the PRISMS configuration files, this software will parse *template* files in order to retrieve which parameters it shall optimize.\n\nRecords for each optimization loop will be stored in a log file, so that the user can track the evolution of optimized parameters and cost functions. In addition, OptiPRISMS will use this file to avoid reruning preexisting simulations, so that the optimization can be stopped then resumed.\n\nFull description of the algorithm is provided in [[2]](#paper).\n\n## Required materials\n\n- The mesh of the microstructure (in .msh format). One can use [MTEX2Gmsh](https://github.com/DorianDepriester/MTEX2Gmsh/blob/master/MTEX2prisms/MTEX2PRISMS.pdf) [[3]](#mtex2gmsh) to generate a conforming mesh directly from EBSD data.\n- [PRISMS-Plasticity software](https://github.com/prisms-center/plasticity).\n- Python 3.6 (or later) with the following modules: numpy, scipy, vtk, pandas and optimparallel (optional).\n- Experimental data, consisting in:\n - a macroscopic tensile curve (strain-stress values as a CSV file),\n\t- SEM-DIC displacement measurements, stored as individual CSV files named sequentially (eg. \"DIC_1.csv\", \"DIC_2.csv\" and so on).\n\t\nEach of these files must have tabular data, ordered this way:\n1. x coordinates of DIC points where DIC measurements are performed,\n2. y coordinates of DIC points where DIC measurements are performed,\n3. x displacements,\n4. y displacements,\n5. correlation coefficients (optional, see [Cost Function](#cost-function) section)\n\n## Cite this project\nIf you use this project, please cite ref. [[2]](#paper). You can use the following BibTeX entry:\n\n```bibtex\n@article{OptiPRISMS,\ntitle = {Crystal Plasticity simulations of in situ tensile tests: A two-step inverse method for identification of CP parameters, and assessment of CPFEM capabilities},\njournal = {International Journal of Plasticity},\npages = {103695},\nyear = {2023},\nissn = {0749-6419},\ndoi = {https://doi.org/10.1016/j.ijplas.2023.103695},\nurl = {https://www.sciencedirect.com/science/article/pii/S074964192300181X},\nauthor = {D. Depriester and J.P. Goulmy and L. Barrallier},\n}\n```\n\n## Installation\nYou can install the latest release of OptiPRISMS with pip:\n```bash\npip install OptiPRISMS\n```\nOtherwise, you can install the development version from sources:\n```bash\ngit clone https://github.com/DorianDepriester/OptiPRISMS.git\ncd OptiPRISMS\npip install --editable .\n```\n\n## Step-by-step method to run optimization\n\n1. Create template files. They consist in usual configuration files (see [here](https://github.com/prisms-center/plasticity/blob/master/docs/PRISMS_plasticity_user_manual_V1_4_0.pdf) for details), where every value you want to optimize is given a variable name. These names must be precessed by a dollar symbol (``$``, e.g. ``$a`` instead of ``a``).\n2. Edit the configuration file to tune optimization-related parameters (see below for details or check out the [example](https://github.com/DorianDepriester/OptiPRISMS/tree/main/example) folder).\n3. With Python3, run the `optimize` function from `OptiPRISMS` module. E.g.:\n```python\nfrom OptiPRISMS import optimize\nres = optimize(config_file='myConfigFile.ini')\n```\n4. Then, wait a couple of days (or weeks...).\n\nIn the meantime, you can track the progress of optimization by having a look on the [log file](#log-file).\n\n## Configuration file\n\nThis file describes locations of data and parameters for optimization. It divides in sections (some of them are mandatory, other are not).\nSee full examples in [example](example) folder.\n\n### Mandatory sections\n#### [Initial Guess]\n\nProvide here starting values for the variables you want to optimize. The variables names must be consistent with these in templates for PRISMS parameter files (as detailed [here](#step-by-step-method-to-run-optimization)).\n\n#### [Bounds]\n\n- **lower**: list of lower bounds\n- **upper**: list of upper bounds\n\n#### [PRISMS]\n\n- **prm file**: path to the main parameter file template\n- **latent hardening ratio** : path to latent hardening ratio template\n- **path to prisms**: path to PRISMS-Plasticity executable file. This entry is not required if Slurm is used (see [\\[Slurm\\]] section).\n\n#### [Experimental Data]\n\n- **DIC data**: pattern describing the path to CSV files with DIC measurements (without step number nor extension). \nOptiPRISMS will automatically append the step number and the CSV extension to this pattern. For instance,\nif one wants to use files ``DIC_1.csv`` and ``DIC_2.csv``, this parameter should be\nset to ``DIC_``.\n- **DIC time steps** *(optional)*: increment numbers corresponding to each step of DIC measurements. \nIf not set, they will be inferred from option `set Tabular Time Output Table` in prm file.\n- **tensile curve**: path to strain-stress values of tensile curve\n- **tensile direction** *(optional)*: Direction of measured stress and strain. It can be ``x`` or ``y``. \nThe default value is ``x``. \n\n#### [Cost Function]\n\n- **weight on tensile curve**: weight to apply to the tensile curve in the overall cost function\n- **penalty**: penalty value to raise if the simulation fails\n- **weight by correlation coefficients**: if enabled, the kinematic cost function will weight the \ndisplacement errors by the inverse of the correlation coefficients. The latter will\nbe read from the 6th column of the DIC CSV files (as detailed in [Required Materials](#required-materials) section)\n\n#### [Log File]\n\n- **file path**: path to log file\n\n### Optional sections\n\n#### [Minimize]\n\nPass here any optional parameter(s) for the ``options`` argument of `scipy.optimize.minimize`. See [the options for ``scipy.optimize.minimize`` with L-BFGS-B method for available arguments](https://docs.scipy.org/doc/scipy/reference/optimize.minimize-lbfgsb.html#optimize-minimize-lbfgsb).\n\n#### [Minimize parallel]\n\nThis section allows to use a parallel implementation of the L-BFGS-B minimizer [[3]](#optim_parallel), through the ``minimize_parallel`` function (from [``optimparallel``](https://github.com/florafauna/optimParallel-python) module).\n\n- **use parallel minimizer**: whether to use `minimize_parallel`, instead of `scipy.optimize.minimize` (default is No)\n\nIn addition, any keyword argument normally passed to the `parallel` option of `minimize_parallel` can be defined in this section. See [the related documentation](https://github.com/florafauna/optimParallel-python/blob/8bf622be1431ba10fef1d795521a2b1d86307c9d/src/optimparallel.py#L170) for available options.\n\n#### [Slurm]\n\n- **use Slurm**: whether to use the Slurm workload manager. Default is No.\n- **batch file**: path to batch file to use for submitting a job running PRISMS-Plasticity. The path to the prm file will be passed as the first argument of this script.\n\n#### [Debug]\n\n- **fake simulations**: If Yes, each simulation is not computed. The related commands are printed instead. Default is No.\n- **fake deletions**: Turn off automatic removal of simulation results (step 5 in [How it works](#how-it-works) section). Default is No.\n\n## References\n<a id=\"prisms\">[1]</a> Yaghoobi et al., (2019). Prisms-plasticity: An open-source crystal plasticity finite element software. Computational Materials Science, 169:109078, https://doi.org/10.1016/j.commatsci.2019.109078\n\n<a id=\"paper\">[2]</a> Depriester et al., (2023). Crystal Plasticity Simulations of in Situ Tensile Tests: A Two-Step Inverse Method for Identification of CP Parameters, and Assessment of CPFEM Capabilities. International Journal of Plasticity, https://doi.org/10.1016/j.ijplas.2023.103695\n\n<a id=\"mtex2gmsh\">[3]</a> Depriester et al., (2020). MTEX2Gmsh: a tool for generating 2D meshes from EBSD data. Journal of Open Source Software, 5(52):2094, https://doi.org/10.21105/joss.02094\n\n<a id=\"optim_parallel\">[4]</a> Gerber, F. and Furrer, R. (2019). optimParallel: An R package providing a parallel version of the L-BFGS-B optimization method, The R Journal, 11(1):352\u2013358, http://doi.org/10.32614/RJ-2019-030\n",
"bugtrack_url": null,
"license": "GNU Lesser General Public License v2.1",
"summary": "Identifies Crystal Plasticity (CP) parameters by inverse analysis based on CPFEM simulations performed using PRISMS-Plasticity",
"version": "1.1.1",
"project_urls": {
"Homepage": "https://github.com/DorianDepriester/OptiPRISMS"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f20d80fe1530670c6e389bfcf23148c7a815f6c0852b94c80e0f91b24e890ae2",
"md5": "e83c1bb4935dc548021da08b16a50ea5",
"sha256": "cbc40e7650bce6edd4444b8d2d73956cd2bb4b72a9b3bc2050ab9656b90745b6"
},
"downloads": -1,
"filename": "OptiPRISMS-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e83c1bb4935dc548021da08b16a50ea5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 24814,
"upload_time": "2023-07-04T07:47:45",
"upload_time_iso_8601": "2023-07-04T07:47:45.569534Z",
"url": "https://files.pythonhosted.org/packages/f2/0d/80fe1530670c6e389bfcf23148c7a815f6c0852b94c80e0f91b24e890ae2/OptiPRISMS-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a8fa2322fc0ccf54e840a8c4dfa5797771939348ca76c3e48bb4476424c357a2",
"md5": "f8e9de7763d20ec05f194930ae1ba84e",
"sha256": "f49cdaaef286789146cf2f07cec87ec58bd7de2db1f3ceddc3a9baf522235fc5"
},
"downloads": -1,
"filename": "OptiPRISMS-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "f8e9de7763d20ec05f194930ae1ba84e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 23440,
"upload_time": "2023-07-04T07:47:47",
"upload_time_iso_8601": "2023-07-04T07:47:47.216319Z",
"url": "https://files.pythonhosted.org/packages/a8/fa/2322fc0ccf54e840a8c4dfa5797771939348ca76c3e48bb4476424c357a2/OptiPRISMS-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-04 07:47:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DorianDepriester",
"github_project": "OptiPRISMS",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "optiprisms"
}
JSON
