# Modelica Builder
The Modelica Builder project aims to make in-place modifications to Modelica language files easier.
The principal use case is to load, modify using higher level abstracted methods, and then save the
resulting file. The user has access to the entire Abstract Syntax Tree of the entire Modelica grammar.
The Modelica Builder project does not:
* Compile nor check for syntax validity
## Install
`pip install modelica-builder`
## Usage
ModBuild provides specific methods for reading and modifying files.
```python
from modelica_builder.model import Model
# parse the model file
source_file = 'DCMotor.mo'
model = Model(source_file)
# do read and modify the model
# refer to modelica_builder.model.Model class methods to see what's available
name = model.get_name()
model.set_name('New' + name)
model.add_connect('some.component.port_a', 'another.component.port_b')
model.insert_component('MyComponentType', 'myInst',
modifications={'arg1': '1234'}, string_comment='my comment',
annotations=['my annotation'], insert_index=0)
# save the result
model.save_as('NewDCMotor.mo')
```
You can also define your own classes for editing the file
```python
from modelica_builder.edit import Edit
from modelica_builder.selector import Selector
from modelica_builder.transformation import SimpleTransformation
class MySelector(Selector):
# implement class for selecting AST nodes
# define the edit to make to the node's text and combine it with the selector
edit = Edit.make_replace('FOOBAR')
selector = MySelector()
transformation = SimpleTransformation(selector, edit)
model = Model('my_modelica_file.mo')
# add your custom transformation
model.add(transformation)
model.save_as('result.mo')
```
Transformations specify what nodes to change and how to change them. This is done by combining
Selectors and Edits. Selectors specify how to select nodes in the AST, and edits are modifications
(insert, replace, delete) to the text of selected nodes.
A Transformer is a collection of Transformations, which can then be applied to a file.
See the tests for more examples and information.
## Development
For developers, dependency management is through [Poetry](https://python-poetry.org/docs/). Installation is accomplished by running `pip install poetry`.
```bash
pip install poetry
# install after cloning repo
poetry install
```
If you change the source grammar file you need to regenerate the parser and lexer.
With docker installed, run these commands from this the repo's root directory
```bash
# build Antlr container
docker build -t antlr4:latest -f antlr/Dockerfile .
# run parser generator for python
docker run -v "$(pwd)/modelica_builder/modelica_parser":/var/antlrResult \
antlr4:latest \
-Dlanguage=Python3 /var/antlrResult/modelica.g4
# commit results along with grammar file
```
If not using Docker, install antlr4 following [these instructions](https://github.com/antlr/antlr4/blob/master/doc/getting-started.md#installation).
```bash
# in modelica_building/modelica_parser
antlr4 -Dlanguage=Python3 modelica.g4
# commit results along with grammar file
```
## Managed Tasks
### Updating Licenses
To apply the copyright/license to all the files, run the following managed task. To update, then update the
script, and then rerun the managed task.
```bash
./setup.py update_licenses
```
### Testing
To run the tests, simply run the following:
```bash
poetry run pytest
```
### Known Issues
* The transformations occur on strings which are immutable. Need to investigate using byte arrays. This does not cause errors, but can be slow when parsing really large modelica files.
## Release Instructions
1. Bump version to <NEW_VERSION> in pyproject.toml (use semantic versioning, e.g., 0.5.0, 0.5.1.rc1).
1. Run `poetry run pre-commit run --all-files`
1. In a prep-release branch, push the changes to GitHub and draft a release against the latest branch.
* Run 'auto-generate changelog' and copy the contents to the CHANGELOG.md. Cull any items that are repeated.
* Discard the draft release (you will create an official one off of the main branch later)
1. Merge the prep-release branch into develop.
1. From command line, merge develop into main with: `git checkout main; git pull; git merge --ff-only origin develop; git push`
1. In GitHub, tag the release against main. Copy and paste the changelog entry into the notes. Verify the release is posted to PyPI.
Raw data
{
"_id": null,
"home_page": "https://github.com/urbanopt/modelica-builder/releases",
"name": "modelica-builder",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.9",
"maintainer_email": null,
"keywords": "Modelica, Physics-based Modeling, Abstract Syntax Tree, AST",
"author": "Nicholas Long",
"author_email": "nicholas.long@nrel.gov",
"download_url": "https://files.pythonhosted.org/packages/0c/06/3c7d415fdf2e6b3ade2c14e87e4d587478a950ad943979886465b29c395f/modelica_builder-0.6.0.tar.gz",
"platform": null,
"description": "# Modelica Builder\n\nThe Modelica Builder project aims to make in-place modifications to Modelica language files easier.\nThe principal use case is to load, modify using higher level abstracted methods, and then save the\nresulting file. The user has access to the entire Abstract Syntax Tree of the entire Modelica grammar.\n\nThe Modelica Builder project does not:\n\n* Compile nor check for syntax validity\n\n## Install\n\n`pip install modelica-builder`\n\n## Usage\n\nModBuild provides specific methods for reading and modifying files.\n\n```python\nfrom modelica_builder.model import Model\n\n# parse the model file\nsource_file = 'DCMotor.mo'\nmodel = Model(source_file)\n\n# do read and modify the model\n# refer to modelica_builder.model.Model class methods to see what's available\nname = model.get_name()\nmodel.set_name('New' + name)\nmodel.add_connect('some.component.port_a', 'another.component.port_b')\nmodel.insert_component('MyComponentType', 'myInst',\n modifications={'arg1': '1234'}, string_comment='my comment',\n annotations=['my annotation'], insert_index=0)\n\n# save the result\nmodel.save_as('NewDCMotor.mo')\n```\n\nYou can also define your own classes for editing the file\n\n```python\nfrom modelica_builder.edit import Edit\nfrom modelica_builder.selector import Selector\nfrom modelica_builder.transformation import SimpleTransformation\n\nclass MySelector(Selector):\n # implement class for selecting AST nodes\n\n# define the edit to make to the node's text and combine it with the selector\nedit = Edit.make_replace('FOOBAR')\nselector = MySelector()\ntransformation = SimpleTransformation(selector, edit)\n\nmodel = Model('my_modelica_file.mo')\n# add your custom transformation\nmodel.add(transformation)\nmodel.save_as('result.mo')\n```\n\nTransformations specify what nodes to change and how to change them. This is done by combining\nSelectors and Edits. Selectors specify how to select nodes in the AST, and edits are modifications\n(insert, replace, delete) to the text of selected nodes.\n\nA Transformer is a collection of Transformations, which can then be applied to a file.\n\nSee the tests for more examples and information.\n\n## Development\n\nFor developers, dependency management is through [Poetry](https://python-poetry.org/docs/). Installation is accomplished by running `pip install poetry`.\n\n```bash\n pip install poetry\n\n # install after cloning repo\n poetry install\n```\n\nIf you change the source grammar file you need to regenerate the parser and lexer.\n\nWith docker installed, run these commands from this the repo's root directory\n\n```bash\n # build Antlr container\n docker build -t antlr4:latest -f antlr/Dockerfile .\n\n # run parser generator for python\n docker run -v \"$(pwd)/modelica_builder/modelica_parser\":/var/antlrResult \\\n antlr4:latest \\\n -Dlanguage=Python3 /var/antlrResult/modelica.g4\n\n # commit results along with grammar file\n```\n\nIf not using Docker, install antlr4 following [these instructions](https://github.com/antlr/antlr4/blob/master/doc/getting-started.md#installation).\n\n```bash\n # in modelica_building/modelica_parser\n antlr4 -Dlanguage=Python3 modelica.g4\n\n # commit results along with grammar file\n```\n\n## Managed Tasks\n\n### Updating Licenses\n\nTo apply the copyright/license to all the files, run the following managed task. To update, then update the\nscript, and then rerun the managed task.\n\n```bash\n ./setup.py update_licenses\n```\n\n### Testing\n\nTo run the tests, simply run the following:\n\n```bash\n poetry run pytest\n```\n### Known Issues\n\n* The transformations occur on strings which are immutable. Need to investigate using byte arrays. This does not cause errors, but can be slow when parsing really large modelica files.\n\n## Release Instructions\n\n1. Bump version to <NEW_VERSION> in pyproject.toml (use semantic versioning, e.g., 0.5.0, 0.5.1.rc1).\n1. Run `poetry run pre-commit run --all-files`\n1. In a prep-release branch, push the changes to GitHub and draft a release against the latest branch.\n * Run 'auto-generate changelog' and copy the contents to the CHANGELOG.md. Cull any items that are repeated.\n * Discard the draft release (you will create an official one off of the main branch later)\n1. Merge the prep-release branch into develop.\n1. From command line, merge develop into main with: `git checkout main; git pull; git merge --ff-only origin develop; git push`\n1. In GitHub, tag the release against main. Copy and paste the changelog entry into the notes. Verify the release is posted to PyPI.\n\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Modelica builder enables programmatic parsing and modification of Modelica files.",
"version": "0.6.0",
"project_urls": {
"Documentation": "https://github.com/urbanopt/modelica-builder",
"Homepage": "https://github.com/urbanopt/modelica-builder/releases",
"Repository": "https://github.com/urbanopt/modelica-builder"
},
"split_keywords": [
"modelica",
" physics-based modeling",
" abstract syntax tree",
" ast"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a96485800a0945b7f6146ea3ac8752dced22ad83d4559c5fa14fdf9415e72cac",
"md5": "5b272a8131b19917b218647a757031b8",
"sha256": "60a66dda3de0604a5bd12fd95e43ea21b72d97933ee0fbcc10a0da1df4798f78"
},
"downloads": -1,
"filename": "modelica_builder-0.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5b272a8131b19917b218647a757031b8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.9",
"size": 89464,
"upload_time": "2024-11-14T20:38:58",
"upload_time_iso_8601": "2024-11-14T20:38:58.809776Z",
"url": "https://files.pythonhosted.org/packages/a9/64/85800a0945b7f6146ea3ac8752dced22ad83d4559c5fa14fdf9415e72cac/modelica_builder-0.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0c063c7d415fdf2e6b3ade2c14e87e4d587478a950ad943979886465b29c395f",
"md5": "d6f98bca5ef8d4be979f1fffeaa5916f",
"sha256": "677b9028009d12803c55c4c485ce9ef481c59d551f2312d2c2178f05403895e3"
},
"downloads": -1,
"filename": "modelica_builder-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "d6f98bca5ef8d4be979f1fffeaa5916f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.9",
"size": 82442,
"upload_time": "2024-11-14T20:39:00",
"upload_time_iso_8601": "2024-11-14T20:39:00.140635Z",
"url": "https://files.pythonhosted.org/packages/0c/06/3c7d415fdf2e6b3ade2c14e87e4d587478a950ad943979886465b29c395f/modelica_builder-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-14 20:39:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "urbanopt",
"github_project": "modelica-builder",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "modelica-builder"
}
JSON
