| Name | gotranx JSON |
| Version |
1.1.5
JSON |
| download |
| home_page | None |
| Summary | A declarative language describing ordinary differential equations |
| upload_time | 2024-10-16 13:55:39 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
parser
lark
gotran
ode
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://github.com/finsberg/gotranx/actions/workflows/pre-commit.yml)
[](https://github.com/finsberg/gotranx/actions/workflows/main.yml)
[](https://finsberg.github.io/gotranx)
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
[](https://codspeed.io/finsberg/gotranx)
[](https://joss.theoj.org/papers/40dc8d8287c6188eaab8149ed3bfe60b)
[](https://doi.org/10.5281/zenodo.13938299)
# gotranx
`gotranx` is the next generation General ODE translator. The general idea is that you write your ODE in a high level markup language and use `gotranx` to generate code for solving the ODE in different programming languages. `gotranx` uses [`sympy`](https://www.sympy.org/en/index.html) to create a symbolic representation of the ODE which is used to generate the jacobian and numerical schemes.
- Source code: https://github.com/finsberg/gotranx
- Documentation: https://finsberg.github.io/gotranx/
## Install
Install with pip
```
python3 -m pip install gotranx
```
or for the development version
```
python3 -m pip install git+https://github.com/finsberg/gotranx
```
## Quick start
Define your ODE in a `.ode` file, e.g `file.ode` with the content
```
states(x=1, y=0)
parameters(a=1.0)
dx_dt = a * y
dy_dt = -x
```
which defines the ODE system
$$
\begin{align}
\frac{dx}{dt} &= ay \\
\frac{dy}{dt} &= -x
\end{align}
$$
with the initial conditions $x(0) = 1$ and $y(0) = 0$ and the parameter $a$ with a value of 1.0. Now generate code in python for solving this ODE with the explicit euler scheme using the command
```
gotranx ode2py file.ode --scheme explicit_euler -o file.py
```
which will create a file `file.py` containing functions for solving the ODE. Now you can solve the ode using the following code snippet
```python
import file as model
import numpy as np
import matplotlib.pyplot as plt
s = model.init_state_values()
p = model.init_parameter_values()
dt = 1e-4 # 0.1 ms
T = 2 * np.pi
t = np.arange(0, T, dt)
x_index = model.state_index("x")
x = [s[x_index]]
y_index = model.state_index("y")
y = [s[y_index]]
for ti in t[1:]:
s = model.explicit_euler(s, ti, dt, p)
x.append(s[x_index])
y.append(s[y_index])
plt.plot(t, x, label="x")
plt.plot(t, y, label="y")
plt.legend()
plt.show()
```
Alternatively, you can use a third-party ODE solver, e.g [`scipy.integrate.solve_ivp`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.solve_ivp.html) to solve the ODE by passing in the right-hand side function
```python
import file as model
from scipy.integrate import solve_ivp
import numpy as np
import matplotlib.pyplot as plt
s = model.init_state_values()
p = model.init_parameter_values()
dt = 1e-4 # 0.1 ms
T = 2 * np.pi
t = np.arange(0, T, dt)
res = solve_ivp(
model.rhs,
(0, T),
s,
method="RK45",
t_eval=t,
args=(p,),
)
plt.plot(res.t, res.y.T)
plt.legend()
plt.show()
```
Note that this is a rather artificial example, so check out the demos in the [documentation](https://finsberg.github.io/gotranx/) for more elaborate examples.
## FAQ
**Why should I use `gotranx`?**
The main reasons to use `gotranx` are
1. You want to solve your model using different programming languages (e.g python and C)
2. You want to create a custom numerical scheme that can utilize the symbolic representation of the ODE
3. You would like to share your model in a high level representation (i.e a markup language)
**How does it differ from `scipy.integrate.solve_ivp`?**
`scipy.integrate.solve_ivp` is an ODE solver which takes as input a function defining the right-hand. `gotranx` takes a high level representation of the ODE and can generate code for the right hand side. In other words, you can use `scipy.integrate.solve_ivp` to solve the ODE and use `gotranx` to generate the right hand side.
## Automated tests
### Unit tests
Automated tests can be found in the [`test`](https://github.com/finsberg/gotranx/tree/main/tests) folder. To the run the tests please install the test dependencies
```
python3 -m pip install "gotranx[test]"
```
or if you have cloned the repo locally you can do
```
python3 -m pip install ".[test]"
```
To run the tests you should execute the following command
```
python3 -m pytest
```
Also note that the tests are run on every push and pull request to `main` using [GitHub actions](https://github.com/finsberg/gotranx/actions).
### Linting and formatting
We use [`pre-commit`](https://pre-commit.com) to run the a set of linters and formatters in order to ensure consistent code style. Developers should install the [pre-commit hooks](https://github.com/finsberg/gotranx/blob/main/.pre-commit-config.yaml) by first installing `pre-commit`
```
python3 -m pip install pre-commit
```
and then install the pre-commit hooks
```
pre-commit install
```
To run the hooks on all the files you can do
```
pre-commit run --all
```
For further instructions see the [contributing guide](https://finsberg.github.io/gotranx/CONTRIBUTING.html).
Note also the we run all hooks as a part of our [continuous integration](https://github.com/finsberg/gotranx/actions/workflows/pre-commit.yml), and we are also using [pre-commit.ci](https://pre-commit.ci) to update branches automatically that can fix issues automatically.
### Performance monitoring
We have defined a set of benchmarks that run on every push to the `main` branch using [codspeed](https://codspeed.io). To monitor the performance over time you can check out the [performance report](https://codspeed.io/finsberg/gotranx).
To run the benchmarks locally you can install the `pytest-codspeed` plugin
```
python3 -m pip install pytest-codspeed
```
and run
```
python3 -m pytest tests/ --codspeed
```
You can find more info at https://docs.codspeed.io/benchmarks/python
## License
MIT
## Contributing
Contributions are very welcomed, but please read the [contributing guide](https://finsberg.github.io/gotranx/CONTRIBUTING.html) first
Raw data
{
"_id": null,
"home_page": null,
"name": "gotranx",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "parser, lark, gotran, ode",
"author": null,
"author_email": "Henrik Finsberg <henriknf@simula.no>",
"download_url": "https://files.pythonhosted.org/packages/4c/75/610a904e8d3ce6ef0d1e5c3d1d93cb9064d1aa06b6d9ed6ac5e36f114a00/gotranx-1.1.5.tar.gz",
"platform": null,
"description": "\n\n[](https://github.com/finsberg/gotranx/actions/workflows/pre-commit.yml)\n[](https://github.com/finsberg/gotranx/actions/workflows/main.yml)\n[](https://finsberg.github.io/gotranx)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/psf/black)\n[](https://codspeed.io/finsberg/gotranx)\n[](https://joss.theoj.org/papers/40dc8d8287c6188eaab8149ed3bfe60b)\n[](https://doi.org/10.5281/zenodo.13938299)\n\n# gotranx\n\n`gotranx` is the next generation General ODE translator. The general idea is that you write your ODE in a high level markup language and use `gotranx` to generate code for solving the ODE in different programming languages. `gotranx` uses [`sympy`](https://www.sympy.org/en/index.html) to create a symbolic representation of the ODE which is used to generate the jacobian and numerical schemes.\n\n- Source code: https://github.com/finsberg/gotranx\n- Documentation: https://finsberg.github.io/gotranx/\n\n\n## Install\nInstall with pip\n```\npython3 -m pip install gotranx\n```\nor for the development version\n```\npython3 -m pip install git+https://github.com/finsberg/gotranx\n```\n\n## Quick start\nDefine your ODE in a `.ode` file, e.g `file.ode` with the content\n```\nstates(x=1, y=0)\nparameters(a=1.0)\n\ndx_dt = a * y\ndy_dt = -x\n```\nwhich defines the ODE system\n\n$$\n\\begin{align}\n\\frac{dx}{dt} &= ay \\\\\n\\frac{dy}{dt} &= -x\n\\end{align}\n$$\n\nwith the initial conditions $x(0) = 1$ and $y(0) = 0$ and the parameter $a$ with a value of 1.0. Now generate code in python for solving this ODE with the explicit euler scheme using the command\n```\ngotranx ode2py file.ode --scheme explicit_euler -o file.py\n```\nwhich will create a file `file.py` containing functions for solving the ODE. Now you can solve the ode using the following code snippet\n\n```python\nimport file as model\nimport numpy as np\nimport matplotlib.pyplot as plt\n\ns = model.init_state_values()\np = model.init_parameter_values()\ndt = 1e-4 # 0.1 ms\nT = 2 * np.pi\nt = np.arange(0, T, dt)\n\nx_index = model.state_index(\"x\")\nx = [s[x_index]]\ny_index = model.state_index(\"y\")\ny = [s[y_index]]\n\nfor ti in t[1:]:\n s = model.explicit_euler(s, ti, dt, p)\n x.append(s[x_index])\n y.append(s[y_index])\n\nplt.plot(t, x, label=\"x\")\nplt.plot(t, y, label=\"y\")\nplt.legend()\nplt.show()\n```\n\n\nAlternatively, you can use a third-party ODE solver, e.g [`scipy.integrate.solve_ivp`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.solve_ivp.html) to solve the ODE by passing in the right-hand side function\n\n```python\nimport file as model\nfrom scipy.integrate import solve_ivp\nimport numpy as np\nimport matplotlib.pyplot as plt\n\ns = model.init_state_values()\np = model.init_parameter_values()\ndt = 1e-4 # 0.1 ms\nT = 2 * np.pi\nt = np.arange(0, T, dt)\n\nres = solve_ivp(\n model.rhs,\n (0, T),\n s,\n method=\"RK45\",\n t_eval=t,\n args=(p,),\n)\n\nplt.plot(res.t, res.y.T)\nplt.legend()\nplt.show()\n```\n\nNote that this is a rather artificial example, so check out the demos in the [documentation](https://finsberg.github.io/gotranx/) for more elaborate examples.\n\n## FAQ\n\n**Why should I use `gotranx`?**\nThe main reasons to use `gotranx` are\n\n1. You want to solve your model using different programming languages (e.g python and C)\n2. You want to create a custom numerical scheme that can utilize the symbolic representation of the ODE\n3. You would like to share your model in a high level representation (i.e a markup language)\n\n\n**How does it differ from `scipy.integrate.solve_ivp`?**\n`scipy.integrate.solve_ivp` is an ODE solver which takes as input a function defining the right-hand. `gotranx` takes a high level representation of the ODE and can generate code for the right hand side. In other words, you can use `scipy.integrate.solve_ivp` to solve the ODE and use `gotranx` to generate the right hand side.\n\n\n## Automated tests\n\n### Unit tests\nAutomated tests can be found in the [`test`](https://github.com/finsberg/gotranx/tree/main/tests) folder. To the run the tests please install the test dependencies\n```\npython3 -m pip install \"gotranx[test]\"\n```\nor if you have cloned the repo locally you can do\n```\npython3 -m pip install \".[test]\"\n```\nTo run the tests you should execute the following command\n```\npython3 -m pytest\n```\nAlso note that the tests are run on every push and pull request to `main` using [GitHub actions](https://github.com/finsberg/gotranx/actions).\n\n### Linting and formatting\nWe use [`pre-commit`](https://pre-commit.com) to run the a set of linters and formatters in order to ensure consistent code style. Developers should install the [pre-commit hooks](https://github.com/finsberg/gotranx/blob/main/.pre-commit-config.yaml) by first installing `pre-commit`\n```\npython3 -m pip install pre-commit\n```\nand then install the pre-commit hooks\n```\npre-commit install\n```\nTo run the hooks on all the files you can do\n```\npre-commit run --all\n```\nFor further instructions see the [contributing guide](https://finsberg.github.io/gotranx/CONTRIBUTING.html).\n\nNote also the we run all hooks as a part of our [continuous integration](https://github.com/finsberg/gotranx/actions/workflows/pre-commit.yml), and we are also using [pre-commit.ci](https://pre-commit.ci) to update branches automatically that can fix issues automatically.\n\n### Performance monitoring\nWe have defined a set of benchmarks that run on every push to the `main` branch using [codspeed](https://codspeed.io). To monitor the performance over time you can check out the [performance report](https://codspeed.io/finsberg/gotranx).\n\nTo run the benchmarks locally you can install the `pytest-codspeed` plugin\n```\npython3 -m pip install pytest-codspeed\n```\nand run\n```\npython3 -m pytest tests/ --codspeed\n```\nYou can find more info at https://docs.codspeed.io/benchmarks/python\n\n\n## License\nMIT\n\n## Contributing\nContributions are very welcomed, but please read the [contributing guide](https://finsberg.github.io/gotranx/CONTRIBUTING.html) first\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A declarative language describing ordinary differential equations",
"version": "1.1.5",
"project_urls": {
"Homepage": "https://github.com/finsberg/gotranx"
},
"split_keywords": [
"parser",
" lark",
" gotran",
" ode"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5f841b784e690a373032b883931c0ccb2a62f0301187e04fe9dce14fe85002d0",
"md5": "4d3ade0d9abc48b1c74eb3dd92689444",
"sha256": "51811c8cca614e5a692716acda532997c41c699e232e351e18ef8797152615f0"
},
"downloads": -1,
"filename": "gotranx-1.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4d3ade0d9abc48b1c74eb3dd92689444",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 50839,
"upload_time": "2024-10-16T13:55:38",
"upload_time_iso_8601": "2024-10-16T13:55:38.099872Z",
"url": "https://files.pythonhosted.org/packages/5f/84/1b784e690a373032b883931c0ccb2a62f0301187e04fe9dce14fe85002d0/gotranx-1.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4c75610a904e8d3ce6ef0d1e5c3d1d93cb9064d1aa06b6d9ed6ac5e36f114a00",
"md5": "12638cf5d56aff36a2fd149bad482591",
"sha256": "3f9c1aa45128cf351a03ffb48df53ff7e7c8b06db19e27924871ce30a62e44e0"
},
"downloads": -1,
"filename": "gotranx-1.1.5.tar.gz",
"has_sig": false,
"md5_digest": "12638cf5d56aff36a2fd149bad482591",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 59826,
"upload_time": "2024-10-16T13:55:39",
"upload_time_iso_8601": "2024-10-16T13:55:39.696928Z",
"url": "https://files.pythonhosted.org/packages/4c/75/610a904e8d3ce6ef0d1e5c3d1d93cb9064d1aa06b6d9ed6ac5e36f114a00/gotranx-1.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-16 13:55:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "finsberg",
"github_project": "gotranx",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gotranx"
}
