diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..47d2259 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,444 @@ + +Contributing +============ + +- `How to add a new calculation + strategy <#How-to-add-a-new-calculation-strategy>`__ + + - `Preliminary Checks <#Preliminary-Checks>`__ + - `Adding New Parameters <#Adding-New-Parameters>`__ + - `Strategy Implementation <#Strategy-Implementation>`__ + - `Method Specifications <#Method-Specifications>`__ + + - `Dependencies <#Dependencies>`__ + - `Calculate method <#Calculate-method>`__ + +- `How to add a new parameter <#How-to-add-a-new-parameter>`__ + + - `Unit Conversion <#Unit-Conversion>`__ + +- `Linting <#Linting>`__ +- `Git Guidelines <#Git-Guidelines>`__ + + - `Branching Strategy <#Branching-Strategy>`__ + - `Commit Message Format <#Commit-Message-Format>`__ + + - `Types <#Types>`__ + + - `Best Practices for Pull + Requests <#Best-Practices-for-Pull-Requests>`__ + +- `SPICE <#SPICE>`__ + +How to add a new calculation strategy +------------------------------------- + +Preliminary Checks +------------------ + +1. Review Existing Strategies: Inspect all the calculation strategies in + the calculation_strategies folder to ensure your strategy hasn’t + already been implemented. +2. Review Parameters: Examine the parameters defined in + ``/data/default.json``. Determine if new parameters are needed for + your strategy. + +Adding New Parameters +--------------------- + +3. Parameter Addition: If your strategy introduces new parameters, add + them to the ``default.json`` file. Refer to the Adding a New + Parameter section for detailed guidance.4. Check all the existing + Nodes you can use. The list of existing nodes and their calculation + strategy can be found in ``src/controler/controller.py``. + +Strategy Implementation +----------------------- + +4. Utilize Existing Nodes: Explore the list of nodes in + ``src/controller/controller.py``\ to understand the available + calculation strategies. Avoid recalculating nodes. + +.. code:: python + + self.engine.add_or_update_node('frequency_vector', FrequencyVectorStrategy()) + self.engine.add_or_update_node('resistance', AnalyticalResistanceStrategy()) + self.engine.add_or_update_node('Nz', AnalyticalNzStrategy()) + ... + +DO NOT recalculate the same node with a different strategy. Instead, +apply your new strategy to an existing node. + +5. If your calculation strategy is not implemented, create a new file in + the ``src/model/strategies/strategy_lib/`` folder with the name of + your calculation strategy. + +This file should: - Inherit from the ``CalculationStrategy`` class. - +Implement the ``calculate`` method. - Implement the ``get_dependencies`` +method. + +6. Node Association: Incorporate your newly created strategy into the + controller by assigning it to a node. + +.. code:: python + + + self.engine.add_or_update_node('node_name', YourStrategy()) + +Method Specifications +--------------------- + +Dependencies +~~~~~~~~~~~~ + +- The get_dependencies method must return a list of required parameters + or nodes as strings, matching their names in the default.json file or + controller. ### Calculate method The ``calculate`` method must return + the result of the calculation. The method takes two arguments: +- ``dependencies``: A dictionary containing the values of all the nodes + available in the engine. The keys are the names of the nodes, and the + values are the results of the calculation. +- ``parameters``: An instance of the ``InputParameters`` class + containing the values of the parameters entered by the user. + +This method must return the result of the calculation. The result can be +on of the following: - A single value (int, float, etc.) - A Tensor (2D +array) containing the result of the calculation for each frequency +value. The first column must be the frequency values or (the x_axis for +the plot), and the following columns must be the result of the +calculation. + +ALL OUTPUTS MUST BE IN SI UNITS in linear scale (no dB, no log scale). + +Examples : +~~~~~~~~~~ + +.. code:: python + + class AnalyticalResistanceStrategy(CalculationStrategy): + + def calculate(self, dependencies: dict, parameters: InputParameters): + N = parameters.data['nb_spire'] + Rs = parameters.data['ray_spire'] + rho = parameters.data['rho_whire'] + return N * (2 * np.pi * Rs) * rho + + @staticmethod + def get_dependencies(): + return ['nb_spire', 'ray_spire', 'rho_whire'] + +.. code:: python + + class AnalyticalImpedanceStrategy(CalculationStrategy): + + def calculate(self, dependencies: dict, parameters: InputParameters): + R = dependencies['resistance'] + L = dependencies['inductance'] + C = dependencies['capacitance'] + + frequency_vector = dependencies['frequency_vector'] + + + vectorized_impedance = np.vectorize(self.calculate_impedance) + impedance_values = vectorized_impedance(R, L, C, frequency_vector) + frequency_impedance_tensor = np.column_stack((frequency_vector, impedance_values)) + return frequency_impedance_tensor + + def calculate_impedance(self, R, L, C, f): + impedance_num = (R ** 2) + (L * 2 * np.pi * f) ** 2 + impedance_den = (1 - L * C * (2 * np.pi * f) ** 2) ** 2 + (R * C * (2 * np.pi * f)) ** 2 + return np.sqrt(impedance_num / impedance_den) + + @staticmethod + def get_dependencies(): + return ['resistance', 'inductance', 'capacitance', 'frequency_vector'] + +How to add a new parameter +-------------------------- + +1. **Existing Parameters:** Verify if the new parameter exists within + /data/default.json. +2. **Addition:** Introduce new parameters to ``default.json`` as needed, + adhering to the specified format: The file must be in the following + format: + +.. code:: json + + { "section_name": + { + "param_name": { + "default": XX, + "min": XX, + "max": XX, + "description": "Short description, used for the user interface", + "input_unit": "", + "target_unit": "" + } + } + } + +Note that the ``section_name`` is the name of the section in the user +interface. The ``param_name`` is the name of the parameter in the user +interface. Each section can have multiple parameters. + +These are the fields that must be filled in if your parameter is a +number that require unit conversion: + +.. code:: json + + "input_unit": "", + "target_unit": "" + +Unit Conversion +~~~~~~~~~~~~~~~ + +For example, you don’t want to input a lenght in mm and write 0.001 m in +the input field. You can define the input unit as mm and the target unit +as m. The user will input 1 mm and the system will convert it to 0.001 +m. + +Utilize the ``pint`` library for unit conversion. Input and target units +should be defined for parameters requiring conversion. For comprehensive +unit support and details, visit Pint’s documentation. + +Example: + +.. code:: json + + "capa_triwire": { + "default": 150, + "min": 10, + "max": 1000, + "description": "Triwire capacitance in picofarads", + "input_unit": "picofarad", + "target_unit": "farad" + } + +Linting +------- + +We use pylint to ensure compliance with PEP8 guidelines. Lint your code +with: + +.. code:: bash + + pylint --rcfile pylintrc src/folder/file.py + +Replace ``src/folder/file.py`` with the path to the file you want to +lint. Check the return of the command to see if there are any errors or +warnings in the code. Adapt and correct the code according to the pylint +output. + +You can read the `pylint +documentation `__ for more +information on how to use pylint. + +Git Guidelines +-------------- + +To maintain the repository’s integrity and streamline development +processes, we adhere to a GitFlow-inspired workflow and specific naming +conventions for branches and commit messages. Below is a comprehensive +guide on how to contribute code to this project effectively. + +Branching Strategy +------------------ + +We use a branching strategy that categorizes work based on the nature of +changes, ensuring that our repository remains organized and manageable. +When starting work on a new feature, bug fix, or other tasks, you must +create a new branch following these conventions: + +- **Feature Branches**: ``engine/branch-name``, ``UI/branch-name``, + ``controller/branch-name`` +- **Refactoring**: ``refactor/branch-name`` + +**Important**: Direct commits to the ``dev`` branch are prohibited. +Always create a new branch for your work, branching off from the latest +``dev`` branch. + +Commit Message Format +--------------------- + +Commit messages should be clear, concise, and follow a formal structure +to simplify the repository’s history. Use the following format: + +:: + + TYPE[TAG] - DESCRIPTION + + [optional body] + + [optional footer(s)] + +**Tags**: Include ``#issue_id`` if your work addresses a specific open +issue. + +Types +~~~~~ + +- ``FEAT``: Introduces a new feature. +- ``FIX``: Fixes a bug. +- ``CHORE``: Changes that don’t affect the source or test files, like + updating dependencies. +- ``REFACTOR``: Code changes that neither fix a bug nor add a feature. +- ``DOC``: Documentation updates. +- ``QUAL``: General code quality improvements. +- ``TEST``: Adds or updates tests. +- ``PERF``: Performance improvements. +- ``REVERT``: Reverts a previous commit. + +For more detailed examples and best practices on commit messages, refer +to `this +article `__. + +Best Practices for Pull Requests +-------------------------------- + +- **Scope**: Keep your pull requests small and focused on a single + feature or bug fix to facilitate the review process. +- **Adherence to Standards**: Ensure your contributions follow the + project’s coding standards and guidelines. +- **Stay Updated**: Regularly update your fork to keep it in sync with + the main project. This helps in minimizing merge conflicts. +- **Linting**: Run the linter on your code before submitting a pull + request to ensure compliance with PEP8 guidelines. +- **Documentation**: Update the documentation if your changes affect + the project’s functionality or require additional information. + +By following these guidelines, you contribute to the efficiency and +clarity of the project, making it easier for others to review your +contributions and maintain the project’s health. + +SPICE +----- + +Simulation Program with Integrated Circuit Emphasis (SPICE) is a +general-purpose analog electronic circuit simulator. It is a powerful +tool for simulating and analyzing circuits, providing valuable insights +into circuit behavior and performance. SPICE is widely used in the +electronics industry for designing and testing circuits, making it an +essential tool for electrical engineers and circuit designers. + +In PLASMAG, we integrate spice simulations to allow the user to create +their own models and have more accurate results. + +How to add a new SPICE model +---------------------------- + +1. Prepare the JSON Configuration for the SPICE Module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each SPICE module is defined in a JSON file, which outlines the circuit +characteristics along with associated parameters and calculation +strategies. Here are the steps to prepare this file: + +1. **Module Key Creation:** Add a new key in the JSON file (e.g., + **spice_new_model**) that will act as a unique identifier for the new + module. + +2. **Defining Module Attributes:** + + - **name:** The name of the module, such as “New OP AMP Model”. + - **description:** A detailed description of the module, used for + the user interface. + - **image:** The filename of the image representing the circuit + (must be pre-added to the relevant images directory). + +3. **Parameters:** Define all necessary parameters for the module. Each + parameter should include: + + - **default, min, max:** Default, minimum, and maximum values. + - **description:** A description of the parameter for the user + interface. + - **input_unit and target_unit:** Input and conversion units, if + applicable. + +4. **Strategies:** + + - Add references to specific calculation strategies used by this + module in the ``src/model/strategies/strategy_lib/`` directory. + - Each strategy must have a **name** and a **file** pointing to the + Python script implementing the strategy. + +Example JSON Section for a New SPICE Module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code:: json + + "spice_new_model" : { + "name" : "New OP AMP Model", + "description" : "An advanced test circuit for the spice simulator", + "image" : "new_op_amp_model.png", + "parameters" : { + "R1": { + "default": 500, + "min": 10, + "max": 10000, + "description": "Spice test resistance", + "input_unit": "ohm", + "target_unit": "ohm" + } + }, + "strategies" : { + "SPICE_impedance" : { + "name" : "SPICE Impedance", + "file" : "src/model/strategies/strategy_lib/SPICE.py" + } + } + } + +2. Implement Calculation Strategies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For each strategy listed in the JSON configuration: + +- Create a Python class in the specified file within + ``src/model/strategies/strategy_lib/``. +- Each class should inherit from the **CalculationStrategy** class and + implement necessary methods such as **calculate** and + **get_dependencies**. +- The calculate method should handle the specific SPICE simulation + logic based on input parameters and dependencies defined in the + module. + +3. Test and Validate +~~~~~~~~~~~~~~~~~~~~ + +Once the new module is configured and the strategies are implemented: + +- Test the module extensively to ensure that it works as expected with + the SPICE simulator. You can try the script outside of PLASMAG in the + ``if __name__ == "__main__"``, with mock data. +- Validate that all parameters and calculations produce accurate and + reliable results. + +4. Update User Documentation and Interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Add any necessary documentation to help users understand how to use + the new SPICE module. + +5. Commit Changes +~~~~~~~~~~~~~~~~~ + +Follow the project’s Git guidelines to commit and push the new module to +the repository: + +- Create a feature branch, e.g., feature/spice_new_model. +- Commit your changes with a clear message describing the addition of + the new SPICE module. +- Open a pull request for review. + +5. MISC +~~~~~~~ + +- Make sure to return the results in SI units for consistency. X-axis + values should be in Hz, or seconds for time-domain simulations. +- If the X-axis is in the time domain, make sure to return the time + vector as the first column of the tensor, with the following label : + “Time” +- If you are returning the Gain and the Phase, make sure to return a + linear Gain, and the phase in radians. The first column should be the + frequency values, the second column the gain, and the third column + the phase, with the following labels : “Frequency”, “Gain”, “Phase” diff --git a/docs/index.rst b/docs/index.rst index 6086eda..cc30c8c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,6 +3,155 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +PLASMAG +======= + +**(Python Library for Accurate Space Magnetometer Adjustments with +Genetics)** + +PLASMAG is a simulation software specifically designed for space +magnetometers. At its core, PLASMAG serves as a comprehensive tool for +the parameters adjustment. + +Currently, PLASMAG is tailored to support search coil type instruments. +However, its architecture is built with flexibility and extensibility in +mind. This means PLASMAG is not only limited to current implementations +but is also designed to easily accommodate the addition of new +instruments and the integration of diverse calculation methods and +models. + +Table of Contents +----------------- + +- `Quick Setup <#quick-setup>`__ +- `Installation <#installation>`__ + + - `Prerequisites <#prerequisites>`__ + - `Installing Conda <#installing-conda>`__ + - `Setting Up the Project <#setting-up-the-project>`__ + +- `Usage <#usage>`__ +- `Availables Models <#availables-models>`__ +- `Documentation <#documentation>`__ +- `Contributing <#contributing>`__ +- `License <#license>`__ +- `Acknowledgments <#acknowledgments>`__ + +Quick Setup +----------- + +Clone the repository : + +.. code:: bash + + git clone https://github.com/LaboratoryOfPlasmaPhysics/PLASMAG + +Usage +----- + +1. Simulation Capabilities: + +- Full Electrokinetic Simulation: Uses SPICE kernel via PySPICE for + comprehensive electrokinetic modeling. +- (WIP) Real Data Fitting: Incorporates a two-step data fitting tool + that includes denoising and neural network fitting for accurate + simulations based on measured data. + +2. Visualization Tools: + +- Adaptive Input Section: Adjusts input options based on the + magnetometer parameter set. +- Real-time Parameter Variation: Sliders and real-time calculations to + visualize the impact of parameter changes. +- Modular Plot Section: Allows up to 5 simultaneous displays of various + products, providing a comprehensive view of simulation results. + +3. Modularity and Flexibility: + +- Strategy Design Pattern: Implements a modular engine design using the + strategy pattern, allowing dynamic changes in computation methods and + easy adaptation to new requirements. +- Parallel Computation: Supports parallelization of computations for + improved efficiency. +- Graph Visualization Tools: Provides full graph visualization to + monitor computation dependencies and processes. + +4. Export and Import Capabilities: + +- Export Data: Allows exporting of any product or parameter for + plotting or later re-importation. + +5. Optimization Module (Work in Progress): + +- Genetic Optimization (DEAP): Utilizes evolutionary algorithms to find + optimal parameter sets. +- Particle Swarm Optimization: Implements swarm intelligence techniques + to explore solution spaces. +- Simulated Annealing: Employs probabilistic techniques to approximate + global optimization. +- Mono-parameter and Multi-parameter Optimization: Supports + optimization for single and multiple parameters. +- Mono-criteria and Multi-criteria Optimization: Handles single and + multiple criteria, combining them into a single framework using + weighted polynomials. + +Availables Models +----------------- + +At the moment, the PLASMAG simulation model has only one model +implemented: a simple search coil MAGNETOMETER analytic model. + +The simulation was validated by comparing the simulation results with +the real data from the JUICE mission. + +The parameters for JUICE’s search coil can be found in the +data/JUICE.json file.” + +The implemented simulation model performs quite well, demonstrating high +accuracy for low frequency values. This is reflected in the impedance +plot, where the plotted curves all maintain consistent levels and +shapes. + +However, challenges arise when extending the analysis to higher +frequency ranges. Specifically, for the NEMI and Closed Loop Transfer +Function (CLTF), the model tends to diverge slightly at high +frequencies. This divergence becomes particularly evident after the +resonance frequency. At this juncture, analytically describing the +‘capacitance’ part of the system grows increasingly difficult, leading +to a slight deviation from expected behaviors. This discrepancy +underlines a current limitation of the model, spotlighting the need for +further refinement and development to enhance its accuracy. + +Documentation +------------- + +To generate project documentation: + +.. code:: bash + + pip install sphinx + cd docs + make html + +Navigate to docs/_build/html/index.html to view the documentation. + +Contributing +------------ + +The project is open to contributions. Please refer to the +`CONTRIBUTING.md `__ file for more information. + +Acknowledgments +--------------- + +- **Maxime RONCERAY** - Developer - LPP/CNRS/X + `contact-me `__ +- **Malik MANSOUR** - Supervisor - LPP/CNRS/X + malik.mansour@lpp.polytechnique.fr +- **Claire REVILLET** - IT/Dev supervisor - CNRS Orleans/LPC2E +- **Guillaume JANNET** - Electronics Engineer - CNRS Orleans/LPC2E + + Welcome to PLASMAG's documentation! =================================== @@ -10,10 +159,12 @@ Welcome to PLASMAG's documentation! :maxdepth: 2 :caption: Contents: - main + installation controler model view + contributing + Indices and tables ================== @@ -21,3 +172,4 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` + diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..74e06ed --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,56 @@ +Installation +============ + +Prerequisites +~~~~~~~~~~~~~ + +Ensure you have Conda installed. If not, follow the instructions here: +https://conda.io/projects/conda/en/latest/user-guide/install/index.html + +Linux conda installation +~~~~~~~~~~~~~~~~~~~~~~~~ + +Linux Conda Installation + +Install Conda using the following commands: + +.. code:: bash + + mkdir -p ~/miniconda3 + wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh + bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3 + rm -rf ~/miniconda3/miniconda.sh + +Add conda to your PATH + +.. code:: bash + + ~/miniconda3/bin/conda init bash + ~/miniconda3/bin/conda init zsh + +Restart your terminal and verify the Conda installation: + +.. code:: bash + + conda --version + +Setting Up the Project +~~~~~~~~~~~~~~~~~~~~~~ + +Create and activate a new Conda environment: + +.. code:: bash + + conda env create -f environment.yml + +Activate the environment + +.. code:: bash + + conda activate PLASMAG + +Run the application + +.. code:: bash + + python PLASMAG.py \ No newline at end of file diff --git a/docs/main.rst b/docs/main.rst deleted file mode 100644 index 033f8f7..0000000 --- a/docs/main.rst +++ /dev/null @@ -1,7 +0,0 @@ -Main Module -=========== - -.. automodule:: src.main - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/user_guide.rst b/docs/user_guide.rst new file mode 100644 index 0000000..a673d2b --- /dev/null +++ b/docs/user_guide.rst @@ -0,0 +1,156 @@ +User Manual +=========== + +This manual is intended to help you get started with PLASMAG. Most of +the features are described exhaustively. + +How to use the program +====================== + +The UI +------ + +The UI is divided into three main sections: the toolbar, the parameter +panel, and the canvas. + +.. figure:: docs/images/img.png + :alt: img.png + + img.png + +Toolbar +------- + +The toolbar is located at the top of the window and contains the +following buttons: + +- **File:** contains the buttons to open and save files. + + - .. figure:: docs/images/img_1.png + :alt: img_1.png + + img_1.png + + - **Export Parameters:** exports the parameters of to a JSON file, + can be edited by hand and imported back + + - **Import Parameters:** imports the parameters from a JSON file, + must be in the correct format + + - **Import Flicker Params :** imports the flicker parameters from a + JSON file, must be in the correct format + + - **Export Results:** exports the results of the simulation to a csv + file than can be opened in Excel or any other spreadsheet software + +- **Options:** contains the buttons to change the settings of the + program. + + - .. figure:: docs/images/img_2.png + :alt: img_2.png + + img_2.png + + - **Change Plot count:** changes the number of plots that are + displayed in the right panel + +Tabs +---- + +.. figure:: docs/images/img_4.png + :alt: img_4.png + + img_4.png + +It’s used to switch between differents functionalities of the program. + +Parameters Section +------------------ + +.. figure:: docs/images/img_5.png + :alt: img_5.png + + img_5.png + +The parameters section is located on the left side of the window and +contains the parameters of the simulation. All of the parameters are +grouped by category. + +How to change a parameter +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Option 1 : - Click on the line edit field of the parameter you want to +change - Enter the new value - Press Enter - If the value is valid, the +calculation will be triggered. If the value is invalid, the field will +turn red and the calculation will not be triggered. + +Option 2: - Click on the line edit field of the parameter you want to +change - Use the sliders to change the value, the value will be updated +in real time and the calculation will be triggered + +At every moment, you can reset the value of a parameter by clicking on +the reset button. Or force trigger the calculation by clicking on the +calculate button. |img_6.png| You can use the frequency range double +slider to select the frequency range you want to simulate. + +Strategy selection +~~~~~~~~~~~~~~~~~~ + +.. figure:: docs/images/img_7.png + :alt: img_7.png + + img_7.png + +One of the most importants features of PLASMAG is to be modular and to +allow the user to choose the strategy he wants to use to simulate a +particular value (like the resistance, the capacitance, etc…). You can +easily implement your own strategy by following the instructions in the +`Contributing Guide `__. If you did everything well, +your strategy will appear in the strategy selection combobox. You can +now select it and it will be used in the simulation. + +When you select a strategy if an error occurs, the error message will be +displayed in a popup. It often means that the parameters are not valid +for the selected strategy, or your implementation is not valid and +implicate cyclic dependencies between differents calculations nodes. + +Canvas +------ + +The canvas is located on the right side of the window and contains the +plots of the simulation. You can adjust the number of plots displayed by +clicking on the options button and changing the plot count (from 1 to 5, +default 3) + +.. figure:: docs/images/img_9.png + :alt: img_9.png + + img_9.png + +Using the combo box you can chose to display whatever you want in the +plot. The list contains every node that can be calculated in the +program. The graph will be updated in real time when you change the +parameters. The data is linear but plotted in a logarithmic scale, for x +and y axis. + +If you want to fit existing data by tunign parameters, you can load a +curve in background by clicking on the load curve button. You can then +select a csv file that contains the curve you want to display. The file +must be in the correct format (frequency, value) and the frequency must +be in Hz. + +Memory +~~~~~~ + +- As PLASMAG is a tuning tool, it’s important to be able to compare the + results of different simulations. To do so, you can save the results + of a simulation by clicking on one of the save button (1,2,3). The + results/parameters will be saved in memory and you can load them back + by clicking on the load button. +- When data are stored in memory, the save button will turn green. +- You can “reset” parameters to the saved state by clicking again on a + green save button. +- Memory is not saved when you close the program. +- You can clear the memory by clicking on the clear memory button. + +.. |img_6.png| image:: docs/images/img_6.png