| Name | gotranx JSON |
| Version |
1.2.0
JSON |
| download |
| home_page | None |
| Summary | A declarative language describing ordinary differential equations |
| upload_time | 2025-01-23 15:55:05 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| 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.13940990)
# 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.9",
"maintainer_email": null,
"keywords": "parser, lark, gotran, ode",
"author": null,
"author_email": "Henrik Finsberg <henriknf@simula.no>",
"download_url": "https://files.pythonhosted.org/packages/10/b5/3ba5113826cd6cbea4016b75d632aa5d4a0b67277542d6e2b9f4bfec18c8/gotranx-1.2.0.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.13940990)\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.2.0",
"project_urls": {
"Homepage": "https://github.com/finsberg/gotranx"
},
"split_keywords": [
"parser",
" lark",
" gotran",
" ode"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "aa9f004253c7cf712d905235c9b9ea63d9201f9908623400661a2097c1524315",
"md5": "aa6f287afc65bddf2014cb42f968db02",
"sha256": "c0884d63bfa1ff32cf4c495322688ffce517c43ff1b511c3395845ef83a2917e"
},
"downloads": -1,
"filename": "gotranx-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aa6f287afc65bddf2014cb42f968db02",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 54728,
"upload_time": "2025-01-23T15:55:04",
"upload_time_iso_8601": "2025-01-23T15:55:04.210384Z",
"url": "https://files.pythonhosted.org/packages/aa/9f/004253c7cf712d905235c9b9ea63d9201f9908623400661a2097c1524315/gotranx-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "10b53ba5113826cd6cbea4016b75d632aa5d4a0b67277542d6e2b9f4bfec18c8",
"md5": "acb0886b9c7804192e5b889ec6f94899",
"sha256": "0c96c86605bfdae7f694d01720cdf2ae5b95a9ea7d1f6f4aa8a7dadace936576"
},
"downloads": -1,
"filename": "gotranx-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "acb0886b9c7804192e5b889ec6f94899",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 61594,
"upload_time": "2025-01-23T15:55:05",
"upload_time_iso_8601": "2025-01-23T15:55:05.871304Z",
"url": "https://files.pythonhosted.org/packages/10/b5/3ba5113826cd6cbea4016b75d632aa5d4a0b67277542d6e2b9f4bfec18c8/gotranx-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-23 15:55:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "finsberg",
"github_project": "gotranx",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gotranx"
}
