diff --git a/docs/source/api/pdfbl.sequential.example_package.rst b/docs/source/api/pdfbl.sequential.example_package.rst deleted file mode 100644 index 6f5d38a..0000000 --- a/docs/source/api/pdfbl.sequential.example_package.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _example_package documentation: - -|title| -======= - -.. |title| replace:: pdfbl.sequential.example_package package - -.. automodule:: pdfbl.sequential.example_package - :members: - :undoc-members: - :show-inheritance: - -|foo| ------ - -.. |foo| replace:: pdfbl.sequential.example_package.foo module - -.. automodule:: pdfbl.sequential.example_package.foo - :members: - :undoc-members: - :show-inheritance: - -|bar| ------ - -.. |bar| replace:: pdfbl.sequential.example_package.bar module - -.. automodule:: pdfbl.sequential.example_package.foo - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api/pdfbl.sequential.rst b/docs/source/api/pdfbl.sequential.rst index 9911936..23bd884 100644 --- a/docs/source/api/pdfbl.sequential.rst +++ b/docs/source/api/pdfbl.sequential.rst @@ -10,21 +10,25 @@ :undoc-members: :show-inheritance: -Subpackages ------------ - -.. toctree:: - pdfbl.sequential.example_package Submodules ---------- -|module| --------- +pdfbl.sequential.pdfadapter module +---------------------------------- + +.. automodule:: pdfbl.sequential.pdfadapter + :members: + :undoc-members: + :show-inheritance: + :no-index: + -.. |module| replace:: pdfbl.sequential.example_submodule module +pdfbl.sequential.sequential_cmi_runner module +--------------------------------------------- -.. automodule:: pdfbl.sequential.example_submodule +.. automodule:: pdfbl.sequential.sequential_cmi_runner :members: :undoc-members: :show-inheritance: + :no-index: diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst index 3f47908..3632dd8 100644 --- a/docs/source/getting-started.rst +++ b/docs/source/getting-started.rst @@ -8,72 +8,5 @@ Getting started ================ -Here are some example templates provided to help you get started with writing your documentation. You can use these templates to create your own documentation. - -Reuse ``.rst`` files across multiple pages ------------------------------------------- - -Here is how you can reuse a reusable block of ``.rst`` files across multiple pages: - -.. include:: snippets/example-table.rst - -.. warning:: - - Ensure that the ``.rst`` file you are including is not too long. If it is too long, it may be better to split it into multiple files and include them separately. - -Refer to a specific section in the documentation ------------------------------------------------- - -You can use the ``ref`` tag to refer to a specific section in the documentation. For example, you can refer to the section below using the ``:ref:`` tag as shown :ref:`here `. - -.. note:: - - Please check the raw ``.rst`` file of this page to see the exact use of the ``:ref:`` tag. - -Embed your code snippets in the documentation ---------------------------------------------- - -Here is how you can write a block of code in the documentation. You can use the ``code-block`` directive to write a block of code in the documentation. For example, you can write a block of code as shown below: - -.. code-block:: bash - - # Create a new environment, without build dependencies (pure Python package) - conda create -n -env python=3.13 \ - --file requirements/tests.txt \ - --file requirements/conda.txt - - # Create a new environment, with build dependencies (non-pure Python package) - conda create -n -env python=3.13 \ - --file requirements/tests.txt \ - --file requirements/conda.txt \ - --file requirements/build.txt - - # Activate the environment - conda activate _env - - # Install your package locally - # `--no-deps` to NOT install packages again from `requirements.pip.txt` - pip install -e . --no-deps - - # Run pytest locally - pytest - - # ... run example tutorials - -.. _attach-image: - -Attach an image to the documentation ------------------------------------- - -Here is how you attach an image to the documentation. The ``/docs/source/img/scikit-package-logo-text.png`` example image is provided in the template. - -.. image:: ./img/scikit-package-logo-text.png - :alt: codecov-in-pr-comment - :width: 400px - :align: center - - -Other useful directives ------------------------ - -Here is how you can do menu selection :menuselection:`Admin --> Settings` and display labels for buttons like :guilabel:`Privacy level`. +Welcome to the ``pdfbl.sequential`` documentation! Please see our GitHub page +`here `_ for more information. diff --git a/docs/source/snippets/example-table.rst b/docs/source/snippets/example-table.rst deleted file mode 100644 index 7c4c11d..0000000 --- a/docs/source/snippets/example-table.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. list-table:: 5 levels of reusing/sharing code - :widths: 5 15 40 40 - :header-rows: 1 - - * - Level - - Name - - Scope - - How to setup - * - 1 - - ``function`` - - Reuse code in the single file. - - See Level 1 tutorial - * - 2 - - ``module`` - - Reuse code across files. - - See Level 2 tutorial - * - 3 - - ``workspace`` - - Reuse code across project folders. - - ``package create workspace`` - * - 4 - - ``system`` - - Reuse code across any files in the computer. - - ``package create system`` - * - 5 - - ``public`` - - Share code as publicly installable package. - - ``package create public`` diff --git a/news/init-doc.rst b/news/init-doc.rst new file mode 100644 index 0000000..0cd5a66 --- /dev/null +++ b/news/init-doc.rst @@ -0,0 +1,23 @@ +**Added:** + +* No news added: Initialize the documentation. + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* + +**Security:** + +* diff --git a/src/pdfbl/sequential/pdfadapter.py b/src/pdfbl/sequential/pdfadapter.py index e26b924..6a63ca5 100644 --- a/src/pdfbl/sequential/pdfadapter.py +++ b/src/pdfbl/sequential/pdfadapter.py @@ -28,11 +28,10 @@ class PDFAdapter: Methods ------- - init_profile(profile_path, qmin=None, qmax=None, xmin=None, xmax=None, - dx=None) + init_profile(profile_path, qmin=None, qmax=None, xmin=None, xmax=None, dx=None) Load and initialize the PDF profile from the given file path with some optional parameters. - init_structures(structure_paths, run_parallel=True) + init_structures(structure_paths : list[str], run_parallel=True) Load and initialize the structures from the given file paths, and generate corresponding PDFGenerator objects. init_contribution(equation_string=None) @@ -40,15 +39,15 @@ class PDFAdapter: the profile. init_recipe() Initialize the FitRecipe object for the fitting process. - set_initial_variable_values(variable_name_to_value) + set_initial_variable_values(variable_name_to_value : dict) Update parameter values from the provided dictionary. - refine_variables(variable_names) + refine_variables(variable_names: list[str]) Refine the parameters specified in the list and in that order. get_variable_names() Get the names of all variables in the recipe. - save_results(mode="str", filename=None) + save_results(mode: str, filename: str=None) Save the fitting results. - """ + """ # noqa: E501 def __init__(self): pass @@ -73,16 +72,21 @@ def init_profile( ---------- profile_path : str The path to the experimental PDF profile file. - qmin : float, optional - The minimum Q value for PDF calculation. Default is None. - qmax : float, optional - The maximum Q value for PDF calculation. Default is None. - xmin : float, optional - The minimum r value for PDF calculation. Default is None. - xmax : float, optional - The maximum r value for PDF calculation. Default is None. - dx : float, optional - The r step size for PDF calculation. Default is None. + qmin : float + The minimum Q value for PDF calculation. The default value is + the one parsed from the profile file. + qmax : float + The maximum Q value for PDF calculation. The default value is the + one parsed from the profile file. + xmin : float + The minimum r value for PDF calculation. The default value is the + one parsed from the profile file. + xmax : float + The maximum r value for PDF calculation. The default value is the + one parsed from the profile file. + dx : float + The r step size for PDF calculation. The default value is the + one parsed from the profile file. """ profile = Profile() parser = PDFParser() @@ -113,9 +117,9 @@ def init_structures(self, structure_paths: list[str], run_parallel=True): Notes ----- Planned features: - - Support cif file manipulation. - - Add/Remove atoms. - - symmetry operations? + - Support cif file manipulation. + - Add/Remove atoms. + - symmetry operations? """ if isinstance(structure_paths, str): structure_paths = [structure_paths] @@ -171,14 +175,19 @@ def init_contribution(self, equation_string=None): Parameters ---------- - equation_string : str, optional - The equation string defining the contribution. If None, a default + equation_string : str + The equation string defining the contribution. The default equation will be generated based on the number of phases. + e.g. + for one phase: "s0*G1", + for two phases: "s0*(s1*G1+(1-s1)*G2)", + for three phases: "s0*(s1*G1+s2*G2+(1-(s1+s2))*G3)", + ... Notes ----- Planned features: - - Support registerFunction for custom equations. + - Support registerFunction for custom equations. """ contribution = FitContribution("pdfcontribution") contribution.setProfile(self.profile) @@ -216,10 +225,10 @@ def init_recipe( Notes ----- Planned features: - - support instructions to - - add variables - - constrain variables of the scatters - - change symmetry constraints + - support instructions to + - add variables + - constrain variables of the scatters + - change symmetry constraints """ recipe = FitRecipe() recipe.addContribution(self.contribution) @@ -302,20 +311,25 @@ def get_variable_names(self) -> list[str]: return list(self.recipe._parameters.keys()) def save_results( - self, mode: Literal["dict", "str"] = "str", filename=None + self, mode: Literal["str", "dict"] = "str", filename=None ): """Save the fitting results. Must be called after refine_parameters. Parameters ---------- - filename : str | None + mode : str + The format to save the results. Options are: + "str" - Save results as a formatted text string. + "dict" - Save results as a JSON-compatible dictionary. + filename : str The path to the output file. If None, results will not be saved to - a file. The default is None. - mode : {"dict", "str"} - The format to save the results. - "str" - Save results as a formatted text string. - "dict" - Save results as a JSON-compatible dictionary. + a file. + + Returns + ------- + str or dict + The fitting results in the specified format. """ fit_results = FitResults(self.recipe) if mode == "str":