diff --git a/docs/conf.py b/docs/conf.py index cf01d1b..0abc37a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -6,7 +6,7 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -project = "pathview" +project = "PathView" copyright = "2025, Tasnim Zulfiqar, James Dark, Remi Delaporte-Mathurin" author = "Tasnim Zulfiqar, James Dark, Remi Delaporte-Mathurin" @@ -24,3 +24,37 @@ html_theme = "sphinx_book_theme" html_static_path = ["_static"] + +html_theme_options = { + "repository_url": "https://github.com/festim-dev/PathView", + "use_repository_button": True, + "use_edit_page_button": True, + "repository_branch": "main", + "path_to_docs": "./docs", + "icon_links": [ + { + "name": "GitHub Discussions", + "url": "https://github.com/festim-dev/pathview/discussions", + "icon": "fa-solid fa-comments", + }, + { + "name": "Slack", + "url": "https://join.slack.com/t/festim-dev/shared_invite/zt-246hw8d6o-htWASLsbdosUo_2nRKCf9g", + "icon": "fa-brands fa-slack", + }, + ], + "article_header_end": [ + "navbar-icon-links", + "article-header-buttons", + ], +} + +html_sidebars = { + "**": [ + "navbar-logo", + "search-button-field", + "sbt-sidebar-nav", + ], +} + +html_title = "PathView Documentation" diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..ae0ea71 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,53 @@ +=============================== +Contributing Guide +=============================== + +Code of Conduct +---------------- + +Please read our `Code of Conduct <../CODE_OF_CONDUCT.md>`_. + +Contributing Guidelines +----------------------- + +**Getting Started** + 1. Fork the repository + 2. Create a feature branch (``git checkout -b awesome-feature``) + 3. Make your changes + 4. Add tests for new functionality if needed + 5. Ensure all tests pass + 6. Submit a pull request + +**Development Standards** + - Follow existing code style and conventions + - Write clear, descriptive commit messages + - Include tests for new features + - Update documentation as needed + - Ensure backwards compatibility when possible + +**Types of Contributions** + - ๐Ÿ› Bug reports and fixes + - โœจ New features and enhancements + - ๐Ÿ“š Documentation improvements + - ๐ŸŽจ UI/UX improvements + - ๐Ÿงช Test coverage improvements + +Communication Channels +----------------------- + +**GitHub Discussions** + - General questions and help + - Feature requests and ideas + - Community showcases + - Development discussions + +**Issues** + - Bug reports + - Specific feature requests + - Documentation issues + +**Pull Requests** + - Provide clear description of changes + - Reference related issues + - Include screenshots for UI changes + - Ensure CI checks pass \ No newline at end of file diff --git a/docs/images/global_vars/0.png b/docs/images/global_vars/0.png new file mode 100644 index 0000000..d9ac6f9 Binary files /dev/null and b/docs/images/global_vars/0.png differ diff --git a/docs/images/global_vars/1.png b/docs/images/global_vars/1.png new file mode 100644 index 0000000..003b1c0 Binary files /dev/null and b/docs/images/global_vars/1.png differ diff --git a/docs/images/global_vars/2.png b/docs/images/global_vars/2.png new file mode 100644 index 0000000..95bde66 Binary files /dev/null and b/docs/images/global_vars/2.png differ diff --git a/docs/images/global_vars/3.png b/docs/images/global_vars/3.png new file mode 100644 index 0000000..15e2890 Binary files /dev/null and b/docs/images/global_vars/3.png differ diff --git a/docs/images/solver_prms/0.png b/docs/images/solver_prms/0.png new file mode 100644 index 0000000..cd54bf2 Binary files /dev/null and b/docs/images/solver_prms/0.png differ diff --git a/docs/images/step_by_step_guide/0.png b/docs/images/step_by_step_guide/0.png new file mode 100644 index 0000000..19e589e Binary files /dev/null and b/docs/images/step_by_step_guide/0.png differ diff --git a/docs/images/step_by_step_guide/1.png b/docs/images/step_by_step_guide/1.png new file mode 100644 index 0000000..e0d02cb Binary files /dev/null and b/docs/images/step_by_step_guide/1.png differ diff --git a/docs/images/step_by_step_guide/2.png b/docs/images/step_by_step_guide/2.png new file mode 100644 index 0000000..a0fb5ff Binary files /dev/null and b/docs/images/step_by_step_guide/2.png differ diff --git a/docs/images/step_by_step_guide/3.png b/docs/images/step_by_step_guide/3.png new file mode 100644 index 0000000..0c14f38 Binary files /dev/null and b/docs/images/step_by_step_guide/3.png differ diff --git a/docs/images/step_by_step_guide/4.png b/docs/images/step_by_step_guide/4.png new file mode 100644 index 0000000..84dc155 Binary files /dev/null and b/docs/images/step_by_step_guide/4.png differ diff --git a/docs/images/step_by_step_guide/5.png b/docs/images/step_by_step_guide/5.png new file mode 100644 index 0000000..7f52712 Binary files /dev/null and b/docs/images/step_by_step_guide/5.png differ diff --git a/docs/images/step_by_step_guide/6.png b/docs/images/step_by_step_guide/6.png new file mode 100644 index 0000000..fb8c6a0 Binary files /dev/null and b/docs/images/step_by_step_guide/6.png differ diff --git a/docs/index.rst b/docs/index.rst index 7be6bb9..766b2c6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,218 +19,33 @@ An interactive visual tool for modeling and simulating nuclear fuel cycle compon :target: https://nodejs.org/ :alt: Node.js 18+ +Overview +======== +PathView is a powerful, user-friendly tool designed for modeling and simulating complex systems through an intuitive visual interface. Whether you're working on nuclear fuel cycle analysis, control systems, or general dynamic modeling, PathView provides the tools you need to build, simulate, and analyze your models effectively. -=============================== -Installation Guide -=============================== - -System Requirements -------------------- - -Before installing PathView, ensure your system meets the following requirements: - -**Required Software:** - - Node.js 18+ and npm - - Python 3.8 or higher - - pip for Python package management - - Git (for development) - - -Installation Steps ------------------- - -1. **Clone the Repository** - - .. code-block:: bash - - git clone https://github.com/festim-dev/pathview.git - cd pathview - -2. **Install Frontend Dependencies** - - .. code-block:: bash - - npm install - -3. **Set Up Python Environment** - - We recommend using a virtual environment: - - .. code-block:: bash - - # Create virtual environment - python -m venv venv - - # Activate virtual environment - # On Linux/macOS: - source venv/bin/activate - - # On Windows: - venv\Scripts\activate - - Alternatively, you can use Conda: - .. code-block:: bash - - conda create -n pathview python=3.8 - conda activate pathview - pip install --upgrade pip - pip install -e . - -4. **Install Backend Dependencies** - - .. code-block:: bash - - pip install -r requirements.txt - -5. **Verify Installation** - - .. code-block:: bash - - # Run both frontend and backend - npm run start:both - - The application should be available at: - - Frontend: http://localhost:5173 - - Backend API: http://localhost:8000 - -=============================== -Example Usage -=============================== - -Here's a simple example to get you started with PathView: - -1. **Start the Application** - - After installation, launch PathView: - - .. code-block:: bash - - npm run start:both - - Navigate to http://localhost:5173 in your browser. - -2. **Load Example Files** - - PathView includes several pre-built example graphs in the `example_graphs/ `_ directory that demonstrate different functionality: - - - ``harmonic_oscillator.json`` - Simple oscillator simulation - - ``pid.json`` - PID controller example - - ``festim_two_walls.json`` - Two-wall diffusion model - - ``linear_feedback.json`` - Linear feedback system - - ``spectrum.json`` - Spectral analysis example - - To load an example: - - - Use the file import functionality in the application - - Select any ``.json`` file from the ``example_graphs/`` directory - - The graph will load with pre-configured nodes and connections - - Click the Run button to run the example - -3. **Create Your Own Graphs** - - - Drag and drop nodes from the sidebar - - Connect nodes by dragging from output handles to input handles - - Configure node parameters in the properties panel - - Use the simulation controls to run your model - - -=============================== -Roadmap -=============================== - -**Core Functionality & Solvers** - - Support more PathSim solvers - - User-defined block class (ie. users writing their own Python classes for blocks) - - Support for user plugins (eg. Chem.Eng., fuel cycle blocks, thermodynamic models, etc.) - -**Graph Management & Import/Export** - - Export graph as Subsystem and load it back - -**User Interface & Experience** - - Improved UI/UX - - Capability to rotate/flip nodes - - Enhanced visualization options - - More styling options for nodes and edges - -**Documentation & Examples** - - More example scenarios - - Annotations and comments on graph - -=============================== -Community Guidelines -=============================== - -Code of Conduct ----------------- - -Please read our `Code of Conduct <../CODE_OF_CONDUCT.md>`_. - -Contributing Guidelines ------------------------ - -**Getting Started** - 1. Fork the repository - 2. Create a feature branch (``git checkout -b awesome-feature``) - 3. Make your changes - 4. Add tests for new functionality if needed - 5. Ensure all tests pass - 6. Submit a pull request - -**Development Standards** - - Follow existing code style and conventions - - Write clear, descriptive commit messages - - Include tests for new features - - Update documentation as needed - - Ensure backwards compatibility when possible - -**Types of Contributions** - - ๐Ÿ› Bug reports and fixes - - โœจ New features and enhancements - - ๐Ÿ“š Documentation improvements - - ๐ŸŽจ UI/UX improvements - - ๐Ÿงช Test coverage improvements - -Communication Channels ------------------------ - -**GitHub Discussions** - Use GitHub Discussions for: - - General questions and help - - Feature requests and ideas - - Community showcases - - Development discussions - -**Issues** - Use GitHub Issues for: - - Bug reports - - Specific feature requests - - Documentation issues - -**Pull Requests** - - Provide clear description of changes - - Reference related issues - - Include screenshots for UI changes - - Ensure CI checks pass - - -=============================== -Support -=============================== - -If you need help with PathView, here are the best ways to get support: +**Key Features:** -- **Documentation**: Start with this documentation -- **GitHub Issues**: For bugs and feature requests -- **Discussions**: For questions and community help -- **Email**: remidm@mit.edu +- **Visual Node-Based Interface**: Drag-and-drop nodes to build complex models +- **Real-Time Simulation**: Execute simulations and see results immediately +.. - **Extensible Architecture**: Support for custom nodes and plugins +- **Multiple Solvers**: Various numerical methods for different problem types +- **Import/Export Capabilities**: Save and share your models easily +- **Cross-Platform**: Runs on Windows, macOS, and Linux -=============================== +Quick Start +=========== -Indices and tables -================== +1. **Install PathView** following our :doc:`installation guide ` +2. **Try the examples** in the :doc:`usage guide ` +3. **Build your first model** with our step-by-step tutorials -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +.. toctree:: + :maxdepth: 2 + :hidden: + installation + usage + contributing + roadmap + support diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..80eaf65 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,74 @@ +=============================== +Installation Guide +=============================== + +System Requirements +------------------- + +Before installing PathView, ensure your system meets the following requirements: + +**Required Software:** + - Node.js 18+ and npm + - Python 3.8 or higher + - pip for Python package management + - Git (for development) + + +Installation Steps +------------------ + +1. **Clone the Repository** + + .. code-block:: bash + + git clone https://github.com/festim-dev/pathview.git + cd pathview + +2. **Install Frontend Dependencies** + + .. code-block:: bash + + npm install + +3. **Set Up Python Environment** + + We recommend using a virtual environment: + + .. code-block:: bash + + # Create virtual environment + python -m venv venv + + # Activate virtual environment + # On Linux/macOS: + source venv/bin/activate + + # On Windows: + venv\Scripts\activate + + Alternatively, you can use Conda: + + .. code-block:: bash + + conda create -n pathview python=3.8 + conda activate pathview + pip install --upgrade pip + pip install -e . + +4. **Install Backend Dependencies** + + .. code-block:: bash + + pip install -r requirements.txt + +5. **Verify Installation** + + .. code-block:: bash + + # Run both frontend and backend + npm run start:both + + The application should be available at: + + - Frontend: http://localhost:5173 + - Backend API: http://localhost:8000 diff --git a/docs/roadmap.rst b/docs/roadmap.rst new file mode 100644 index 0000000..1184381 --- /dev/null +++ b/docs/roadmap.rst @@ -0,0 +1,34 @@ +=============================== +Roadmap +=============================== + +Future Development Plans +------------------------ + +**Core Functionality & Solvers** + - Support more PathSim solvers + - User-defined block class (ie. users writing their own Python classes for blocks) + - Support for user plugins (eg. Chem.Eng., fuel cycle blocks, thermodynamic models, etc.) + +**Graph Management & Import/Export** + - Export graph as Subsystem and load it back + +**User Interface & Experience** + - Improved UI/UX + - Capability to rotate/flip nodes + - Enhanced visualization options + - More styling options for nodes and edges + +**Documentation & Examples** + - More example scenarios + - Annotations and comments on graph + +Contributing to the Roadmap +---------------------------- + +We welcome community input on our development priorities. You can: + +- **Vote on features** in our GitHub Discussions +- **Submit feature requests** through GitHub Issues +- **Contribute code** for features you'd like to see +- **Share use cases** that might influence our roadmap diff --git a/docs/support.rst b/docs/support.rst new file mode 100644 index 0000000..0b44c4b --- /dev/null +++ b/docs/support.rst @@ -0,0 +1,18 @@ +=============================== +Support +=============================== + +If you need help with PathView, here are the best ways to get support: + +**GitHub Discussions** + - General questions and help + - Feature discussions + - Visit: https://github.com/festim-dev/pathview/discussions + +**GitHub Issues** + - Bug reports + - Feature requests + - Documentation issues + - Visit: https://github.com/festim-dev/pathview/issues + + diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000..49123ea --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,203 @@ +=============================== +Usage and Examples +=============================== + +Getting Started +--------------- + +Here's a simple example to get you started with PathView: + +#. **Start the Application** + + After installation, launch PathView: + + .. code-block:: bash + + npm run start:both + + Navigate to http://localhost:5173 in your browser. + +#. **Load Example Files** + + PathView includes several pre-built example graphs in the `example_graphs/ `_ directory that demonstrate different functionality: + + * ``harmonic_oscillator.json`` - Simple oscillator simulation + * ``pid.json`` - PID controller example + * ``festim_two_walls.json`` - Two-wall diffusion model + * ``linear_feedback.json`` - Linear feedback system + * ``spectrum.json`` - Spectral analysis example + + To load an example: + + * Use the file import functionality in the application + * Select any ``.json`` file from the `example_graphs/ `_ directory + * The graph will load with pre-configured nodes and connections + * Click the Run button to run the example + +#. **Create Your Own Graphs** + + * Drag and drop nodes from the sidebar + * Connect nodes by dragging from output handles to input handles + * Configure node parameters in the properties panel + * Use the simulation controls to run your model + +Step by step guide +------------------ + +#. **Start the Application** + + After installation, launch PathView: + + .. code-block:: bash + + npm run start:both + + Navigate to http://localhost:5173 in your browser. + + .. figure:: images/step_by_step_guide/0.png + :width: 600px + :align: center + + PathView main interface after starting the application. + +#. **Add nodes** + + In the left sidebar, drag and drop: + + * under Sources: Sinusoidal source + * under Processing: Delay + * under Output: Scope + + .. figure:: images/step_by_step_guide/1.png + :width: 600px + :align: center + + Dragging nodes from the sidebar to the canvas. + + .. figure:: images/step_by_step_guide/2.png + :width: 600px + :align: center + + PathView interface after adding the three nodes. + +#. **Connect Nodes** + + * Connect the Sinusoidal source to the Delay + * Connect the Sinusoidal source to the Scope + * Connect the Delay to the Scope + + .. figure:: images/step_by_step_guide/3.png + :width: 600px + :align: center + + PathView interface after connecting the nodes. + +#. **Run and visualise results** + + * Click the Run button + * The graph will display the sinusoidal signal and its - slightly - delayed version + + .. figure:: images/step_by_step_guide/4.png + :width: 600px + :align: center + + If you zoom in you can see the delay, but it is very small. + +#. **Configure Nodes** + + Let's change the parameters of the nodes to see how it affects the simulation + + * Select the Graph Editor tab + * Select the Delay node and set the ``tau`` parameter to ``0.1`` + * Select the Sinusoidal source and set the ``frequency`` to ``0.7 Hz`` + * Click the Run button again to see the updated results + + .. figure:: images/step_by_step_guide/5.png + :width: 600px + :align: center + + + .. figure:: images/step_by_step_guide/6.png + :width: 600px + :align: center + + After changing the parameters, the delay is now clearly visible. + +#. **Save Your Graph** + + * Click the Save File button + * Choose a location and filename for your graph + * Click Save to export your graph as a JSON file + +#. **Export graph to python script** + + * Click the Save to Python button + * Choose a location and filename for your Python script + * Click Save to export your graph as a Python script + +Global variables +---------------- + +Global variables can be defined in the Global Variables tab. These variables can be used across multiple nodes in your graph, allowing for easier management of common parameters. + +Let's take the [previous example](#step-by-step-guide). + +#. Go to the Global Variables tab. + + .. figure:: images/global_vars/0.png + :width: 600px + :align: center + +#. Click the "Add Variable" button to create a new global variable. +#. Name the variable ``a`` and set its value to ``0.1``. + + .. figure:: images/global_vars/1.png + :width: 600px + :align: center + + Note: you can remove a variable by clicking the red icon next to it. + +#. Go back to the Graph Editor tab. +#. Select the Delay node. +#. In the node panel, set the ``amplitude`` parameter to ``12 * a`` and the ``frequency`` to ``7 * a``. + + .. figure:: images/global_vars/2.png + :width: 200px + :align: center + + +#. Select the Delay node. +#. Set the ``tau`` parameter to ``a + 0.05``. +#. Click the Run button to see the results. + + .. figure:: images/global_vars/3.png + :width: 600px + :align: center + + + +Solver parameters +----------------- + +The Solver Parameters tab allows you to configure the simulation parameters such as time step, maximum simulation time, and numerical solver settings. + +.. figure:: images/solver_prms/0.png + :width: 600px + :align: center + +Visualisation and post-processing +--------------------------------- + +In the Results tab, you can visualize the simulation results. +Each scope node will have its own plot in the Results tab. +You can toggle the visibility of each line by clicking on it in the legend. + +- **Download CSV**: You can download the simulation results as a CSV file for further analysis. +- **Download HTML**: You can download the simulation results as an HTML file for easy sharing and viewing in a web browser. + +Export to python +------------------ + +For advanced users, PathView allows you to export your graph as a Python script. This feature is useful for integrating your simulation into larger Python projects or for further analysis using Python libraries. + +This is useful for instance for performing parametric studies or sensitivity analysis, where you can easily modify parameters in the Python script and rerun the simulation. diff --git a/src/App.jsx b/src/App.jsx index d5df3ef..60f6c8e 100644 --- a/src/App.jsx +++ b/src/App.jsx @@ -354,7 +354,7 @@ const DnDFlow = () => { const url = URL.createObjectURL(blob); const a = document.createElement('a'); a.href = url; - a.download = 'fuel-cycle-graph.json'; + a.download = 'graph.json'; document.body.appendChild(a); a.click();