From 4d9da075e4dcc62c05d0cc0828b9a4d36424b3b7 Mon Sep 17 00:00:00 2001 From: Toru Seo <34780089+toruseo@users.noreply.github.com> Date: Mon, 8 Apr 2024 21:11:50 +0900 Subject: [PATCH] Update documents --- .github/CONTRIBUTING.md | 12 +++++++++++ .gitignore | 1 + README.md | 47 ++++++++++++----------------------------- pyproject.toml | 6 +++--- 4 files changed, 29 insertions(+), 37 deletions(-) create mode 100644 .github/CONTRIBUTING.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..fc6625a --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,12 @@ +# Contributing Guideline + +For minor changes including bug fixes, please submit a pull request (like [this good example](https://github.com/toruseo/UXsim/pull/29)). +If you want a major change, please start a discussion on the [Issues](https://github.com/toruseo/UXsim/issues) or [Discussions](https://github.com/toruseo/UXsim/discussions) pages first. + +To be merged, your code must pass [test scripts](https://github.com/toruseo/UXsim/tree/main/tests) that are automatically run by the Github Action. +But feel free to send pull requests that fail the tests. +The other people may be able to help. + +`uxsim.py` is the core of the traffic flow simulation. +It must contain codes that are essential for simulation only. +If you have developed useful utilities, please consider to add them as a submodule like the current `ResultGUIViewer`. diff --git a/.gitignore b/.gitignore index fad1d62..a9c1cb5 100644 --- a/.gitignore +++ b/.gitignore @@ -137,6 +137,7 @@ _*.ps1 p*_*.py *.code-workspace .VSCodeCounter/* +.vscode/* # pre-commit .pre-commit-config.yaml diff --git a/README.md b/README.md index ccc1f16..8e673de 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ pip install uxsim ```
-Alternative methods (click to see) +Alternative methods for advanced users (click to see) ### Using pip with custom configuration @@ -104,17 +104,7 @@ This way, you can flexibly customize UXsim on your own.
-## Usage - -Import the module using: -```python -from uxsim import * -``` -and then define your simulation scenario. - -The [Jupyter Notebook Demo](https://github.com/toruseo/UXsim/blob/main/demos_and_examples/demo_notebook_01en.ipynb) summarizes the basic usage and features. -You can also test the [Google Colab demo](http://colab.research.google.com/github/toruseo/UXsim/blob/main/demos_and_examples/demo_notebook_05en_for_google_colab.ipynb). -For further details, please see [demos_and_examples](https://github.com/toruseo/UXsim/tree/main/demos_and_examples) and [UXsim technical documentation](https://toruseo.jp/UXsim/docs/index.html). +## Getting Started As a simple example, the following code will simulate traffic flow in a Y-shaped network. ```python @@ -186,28 +176,22 @@ results:

-## Main Files - -- `uxsim` directory: UXsim main package - - `uxsim/uxsim.py`: UXsim main code - - `uxsim/analyzer.py`: Simulation result analysis code - - `uxsim/utils.py`: UXsim utilities code - - `uxsim/ResultGUIViewer/ResultGUIViewer.py`: Submodule on GUI for visualizing simulation results - - `uxsim/OSMImporter/OSMImporter.py`: Submodule on road network import from OpenStreetMap (experimental) - - `uxsim/files` directory: UXsim utilities files -- `demos_and_examples` directory: Tutorials and examples of UXsim -- `dat` directory: Sample scenario files -- `tests`, `.github` directories: Development-related files - ## Further Reading To learn more about UXsim, please see: - [Simple demo in Jupyter Notebook](https://github.com/toruseo/UXsim/blob/main/demos_and_examples/demo_notebook_01en.ipynb) or [Google Colab](http://colab.research.google.com/github/toruseo/UXsim/blob/main/demos_and_examples/demo_notebook_05en_for_google_colab.ipynb): Interactive demonstrations -- [UXsim Technical Documentation](https://toruseo.jp/UXsim/docs/index.html): Detailed documents on tutorials, simulation mechanism, and specifications of modules/functions - [Demos and examples](https://github.com/toruseo/UXsim/tree/main/demos_and_examples): Various examples using Jupyter Notebooks and Python codes +- [UXsim Technical Documentation](https://toruseo.jp/UXsim/docs/index.html): Detailed documents on tutorials, simulation mechanism, and specifications of modules/functions - [arXiv preprint](https://arxiv.org/abs/2309.17114): Scientific overview +## Main Files + +- `uxsim` directory: UXsim main package + - `uxsim/uxsim.py`: UXsim main code +- `demos_and_examples` directory: Tutorials and examples of UXsim +- `dat` directory: Sample scenario files + ## Terms of Use & License UXsim is released under the MIT License. You are free to use it as long as the source is acknowledged. @@ -220,11 +204,9 @@ When publishing works based on UXsim, please cite: ## Contributing and Discussion Contributions are welcome! -For minor changes, including bug fixes, please submit a pull request. -Please make sure that your code passes the automatic tests in Github Action. -If you want a major change, please start a discussion on the [Issues](https://github.com/toruseo/UXsim/issues) or [Discussions](https://github.com/toruseo/UXsim/discussions) pages first. +Please see the [Contributing Guideline](https://github.com/toruseo/UXsim/blob/main/.github/CONTRIBUTING.md). -If you have any questions or suggestions, please start a discussion on the [Discussions](https://github.com/toruseo/UXsim/discussions) page (in English or Japanese). +If you have any questions or suggestions, please post them to the [Issues](https://github.com/toruseo/UXsim/issues) or [Discussions](https://github.com/toruseo/UXsim/discussions) (in English or Japanese). I (Toru Seo) work on this project in my spare time. Please understand that my response may be delayed. @@ -240,7 +222,4 @@ Specifically, UXsim directly uses the following works: ## Related Links - [Toru Seo (Author)](https://toruseo.jp/index_en.html) -- [Collection of related simulators by Seo](https://toruseo.jp/uxsim/index_en.html) -- Japanese book "[Macroscopic Traffic Simulation: Fundamental Mathematical Theory and Python Implementation](https://www.coronasha.co.jp/np/isbn/9784339052794/)" (Author: [Toru Seo](https://toruseo.jp/), Publisher: [Corona Publishing Co., Ltd.](https://www.coronasha.co.jp/)): UXsim is a significant expansion of the traffic flow simulator *UroborosX* described in this book. -- [Seo Laboratory, Tokyo Institute of Technology](http://seo.cv.ens.titech.ac.jp/en/) -- [Interactive Traffic Flow Simulator that Runs on a Web Browser](http://seo.cv.ens.titech.ac.jp/traffic-flow-demo/bottleneck.html): Play with the same link traffic flow model used in this simulator interactively, and learn the basics of traffic flow and its simulation. +- [Seo Laboratory, Tokyo Institute of Technology](http://seo.cv.ens.titech.ac.jp/en/) \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index fbae732..86163f3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -28,9 +28,9 @@ dependencies = [ dynamic = ["version"] # Version is read from uxsim/__init__.py [project.urls] -"Homepage" = "https://github.com/toruseo/UXsim" -"Download" = "https://github.com/toruseo/UXsim" -"Bug Tracker" = "https://github.com/toruseo/UXsim/issues" +Homepage = "https://github.com/toruseo/UXsim" +Documentation = "https://toruseo.jp/UXsim/docs" +Issues = "https://github.com/toruseo/UXsim/issues" [tool.setuptools] packages = {find = {include = ["uxsim", "uxsim.*"]}}