Reach the whole library through one namespace

CONTRIBUTING.md

@@ -193,6 +193,30 @@ git add .
 git commit -m "Improve performance of time integrator for large systems"
 ```
 
+### Imports in Tutorials and Examples
+
+Anything user-facing — the tutorial notebooks and the `python` examples
+in docstrings — reaches EasyDynamics through a single namespace:
+
+```python
+import easydynamics as edyn
+
+experiment = edyn.Experiment('Vanadium')
+model = edyn.SampleModel(components=edyn.Gaussian(width=0.1))
+```
+
+Every public name is re-exported from `easydynamics`, so this always
+works. Please do not mix in `import easydynamics.sample_model as sm`, or
+reach into a module with
+`from easydynamics.analysis.analysis1d import Analysis1d`: a reader then
+has to scroll back to the imports to find out where a name came from.
+
+If something you need is missing from `edyn.`, add it to `__all__` in
+`src/easydynamics/__init__.py` rather than importing around it.
+
+Inside the library itself, keep importing from the specific module that
+defines a name. Only the public front door is flat.
+
 ---
 
 ## 6. Code Quality Checks

docs/docs/tutorials/analysis.ipynb

@@ -24,7 +24,6 @@
     "import pooch\n",
     "\n",
     "import easydynamics as edyn\n",
-    "import easydynamics.sample_model as sm\n",
     "\n",
     "%matplotlib widget"
    ]
@@ -56,28 +55,28 @@
     "# Example of Analysis with a simple sample model and instrument model\n",
     "# The scattering from vanadium is purely elastic, so we model it with a\n",
     "# delta function\n",
-    "delta_function = sm.DeltaFunction(display_name='DeltaFunction', area=1)\n",
-    "sample_model = sm.SampleModel(\n",
+    "delta_function = edyn.DeltaFunction(display_name='DeltaFunction', area=1)\n",
+    "sample_model = edyn.SampleModel(\n",
     "    components=delta_function,\n",
     ")\n",
     "\n",
     "# The resolution is in this case modeled as a Gaussian. However, we can\n",
     "# add as many components as we like to the resolution model\n",
-    "res_gauss = sm.Gaussian(width=0.1)\n",
+    "res_gauss = edyn.Gaussian(width=0.1)\n",
     "res_gauss.area.fixed = True\n",
-    "resolution_components = sm.ComponentCollection()\n",
+    "resolution_components = edyn.ComponentCollection()\n",
     "resolution_components.append_component(res_gauss)\n",
-    "resolution_model = sm.ResolutionModel(components=resolution_components)\n",
+    "resolution_model = edyn.ResolutionModel(components=resolution_components)\n",
     "\n",
     "# The background model is created in the same way. In this case, we use\n",
     "# a flat background\n",
-    "background_model = sm.BackgroundModel(components=sm.Polynomial(coefficients=[0.001]))\n",
+    "background_model = edyn.BackgroundModel(components=edyn.Polynomial(coefficients=[0.001]))\n",
     "\n",
     "# We combine the resolution abd background model into an instrument\n",
     "# model. This model also contains a small energy offset to account for\n",
     "# instrument misalignment.\n",
     "\n",
-    "instrument_model = sm.InstrumentModel(\n",
+    "instrument_model = edyn.InstrumentModel(\n",
     "    resolution_model=resolution_model,\n",
     "    background_model=background_model,\n",
     ")\n",
@@ -190,19 +189,19 @@
     "# Now we set up the model, similarly to how we set up the model for the\n",
     "# vanadium data.\n",
     "\n",
-    "delta_function = sm.DeltaFunction(display_name='DeltaFunction', area=0.2)\n",
-    "lorentzian = sm.Lorentzian(display_name='Lorentzian', area=0.5, width=0.3)\n",
-    "component_collection = sm.ComponentCollection(\n",
+    "delta_function = edyn.DeltaFunction(display_name='DeltaFunction', area=0.2)\n",
+    "lorentzian = edyn.Lorentzian(display_name='Lorentzian', area=0.5, width=0.3)\n",
+    "component_collection = edyn.ComponentCollection(\n",
     "    components=[delta_function, lorentzian],\n",
     ")\n",
     "\n",
-    "sample_model = sm.SampleModel(\n",
+    "sample_model = edyn.SampleModel(\n",
     "    components=component_collection,\n",
     ")\n",
     "\n",
-    "background_model = sm.BackgroundModel(components=sm.Polynomial(coefficients=[0.001]))\n",
+    "background_model = edyn.BackgroundModel(components=edyn.Polynomial(coefficients=[0.001]))\n",
     "\n",
-    "instrument_model = sm.InstrumentModel(\n",
+    "instrument_model = edyn.InstrumentModel(\n",
     "    background_model=background_model,\n",
     ")\n",
     "\n",
@@ -265,22 +264,22 @@
     "# Let us now fit directly to a diffusion model. We replace the\n",
     "# Lorentzian with a Brownian translational diffusion model and keep the\n",
     "# other parameters the same.\n",
-    "delta_function = sm.DeltaFunction(display_name='DeltaFunction', area=0.2)\n",
-    "component_collection = sm.ComponentCollection(\n",
+    "delta_function = edyn.DeltaFunction(display_name='DeltaFunction', area=0.2)\n",
+    "component_collection = edyn.ComponentCollection(\n",
     "    components=[delta_function],\n",
     ")\n",
-    "diffusion_model = sm.BrownianTranslationalDiffusion(\n",
+    "diffusion_model = edyn.BrownianTranslationalDiffusion(\n",
     "    display_name='Brownian Translational Diffusion', diffusion_coefficient=2.4e-9, scale=0.5\n",
     ")\n",
     "\n",
-    "sample_model = sm.SampleModel(\n",
+    "sample_model = edyn.SampleModel(\n",
     "    components=component_collection,\n",
     "    diffusion_models=diffusion_model,\n",
     ")\n",
     "\n",
-    "background_model = sm.BackgroundModel(components=sm.Polynomial(coefficients=[0.001]))\n",
+    "background_model = edyn.BackgroundModel(components=edyn.Polynomial(coefficients=[0.001]))\n",
     "\n",
-    "instrument_model = sm.InstrumentModel(\n",
+    "instrument_model = edyn.InstrumentModel(\n",
     "    background_model=background_model,\n",
     ")\n",
     "\n",

docs/docs/tutorials/analysis1d.ipynb

@@ -19,8 +19,6 @@
     "import pooch\n",
     "\n",
     "import easydynamics as edyn\n",
-    "import easydynamics.sample_model as sm\n",
-    "from easydynamics.analysis.analysis1d import Analysis1d\n",
     "\n",
     "%matplotlib widget"
    ]
@@ -49,24 +47,24 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Example of Analysis1d with a simple sample model and instrument model\n",
-    "delta_function = sm.DeltaFunction(display_name='DeltaFunction', area=1)\n",
-    "sample_model = sm.SampleModel(\n",
+    "# Example of edyn.Analysis1d with a simple sample model and instrument model\n",
+    "delta_function = edyn.DeltaFunction(display_name='DeltaFunction', area=1)\n",
+    "sample_model = edyn.SampleModel(\n",
     "    components=delta_function,\n",
     ")\n",
     "\n",
-    "res_gauss = sm.Gaussian(width=0.1)\n",
-    "resolution_model = sm.ResolutionModel(components=res_gauss)\n",
+    "res_gauss = edyn.Gaussian(width=0.1)\n",
+    "resolution_model = edyn.ResolutionModel(components=res_gauss)\n",
     "\n",
     "\n",
-    "background_model = sm.BackgroundModel(components=sm.Polynomial(coefficients=[0.001]))\n",
+    "background_model = edyn.BackgroundModel(components=edyn.Polynomial(coefficients=[0.001]))\n",
     "\n",
-    "instrument_model = sm.InstrumentModel(\n",
+    "instrument_model = edyn.InstrumentModel(\n",
     "    resolution_model=resolution_model,\n",
     "    background_model=background_model,\n",
     ")\n",
     "\n",
-    "my_analysis = Analysis1d(\n",
+    "my_analysis = edyn.Analysis1d(\n",
     "    display_name='Vanadium Analysis',\n",
     "    experiment=vanadium_experiment,\n",
     "    sample_model=sample_model,\n",

docs/docs/tutorials/bayesian.ipynb

@@ -24,8 +24,6 @@
     "import pooch\n",
     "\n",
     "import easydynamics as edyn\n",
-    "import easydynamics.sample_model as sm\n",
-    "from easydynamics.analysis.analysis1d import Analysis1d\n",
     "\n",
     "# Make the plots interactive; the Q sliders need the widget backend\n",
     "%matplotlib widget"
@@ -77,17 +75,17 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "vanadium_components = sm.ComponentCollection()\n",
-    "vanadium_components.append_component(sm.Gaussian(width=0.1, area=1, name='Res. Gauss'))\n",
+    "vanadium_components = edyn.ComponentCollection()\n",
+    "vanadium_components.append_component(edyn.Gaussian(width=0.1, area=1, name='Res. Gauss'))\n",
     "\n",
-    "instrument_model = sm.InstrumentModel(\n",
-    "    background_model=sm.BackgroundModel(components=sm.Polynomial(coefficients=[0.001])),\n",
+    "instrument_model = edyn.InstrumentModel(\n",
+    "    background_model=edyn.BackgroundModel(components=edyn.Polynomial(coefficients=[0.001])),\n",
     ")\n",
     "\n",
-    "analysis = Analysis1d(\n",
+    "analysis = edyn.Analysis1d(\n",
     "    display_name='Vanadium Analysis',\n",
     "    experiment=vanadium_experiment,\n",
-    "    sample_model=sm.SampleModel(components=vanadium_components),\n",
+    "    sample_model=edyn.SampleModel(components=vanadium_components),\n",
     "    instrument_model=instrument_model,\n",
     "    Q_index=5,\n",
     ")\n",
@@ -345,15 +343,15 @@
    "source": [
     "# Fresh models, so this analysis is independent of the single-Q one above rather than\n",
     "# sharing its already-sampled components.\n",
-    "all_q_components = sm.ComponentCollection()\n",
-    "all_q_components.append_component(sm.Gaussian(width=0.1, area=1, name='Res. Gauss'))\n",
+    "all_q_components = edyn.ComponentCollection()\n",
+    "all_q_components.append_component(edyn.Gaussian(width=0.1, area=1, name='Res. Gauss'))\n",
     "\n",
     "full_analysis = edyn.Analysis(\n",
     "    display_name='Vanadium, all Q',\n",
     "    experiment=vanadium_experiment,\n",
-    "    sample_model=sm.SampleModel(components=all_q_components),\n",
-    "    instrument_model=sm.InstrumentModel(\n",
-    "        background_model=sm.BackgroundModel(components=sm.Polynomial(coefficients=[0.001])),\n",
+    "    sample_model=edyn.SampleModel(components=all_q_components),\n",
+    "    instrument_model=edyn.InstrumentModel(\n",
+    "        background_model=edyn.BackgroundModel(components=edyn.Polynomial(coefficients=[0.001])),\n",
     "    ),\n",
     ")\n",
     "full_analysis.fit(fit_method='independent')\n",

docs/docs/tutorials/component_collection.ipynb

@@ -20,7 +20,7 @@
     "import matplotlib.pyplot as plt\n",
     "import numpy as np\n",
     "\n",
-    "import easydynamics.sample_model as sm\n",
+    "import easydynamics as edyn\n",
     "\n",
     "%matplotlib widget"
    ]
@@ -32,13 +32,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "component_collection = sm.ComponentCollection()\n",
+    "component_collection = edyn.ComponentCollection()\n",
     "\n",
     "# Creating components\n",
-    "gaussian = sm.Gaussian(display_name='Gaussian', width=0.5, area=1)\n",
-    "dho = sm.DampedHarmonicOscillator(display_name='DHO', center=1.0, width=0.3, area=2.0)\n",
-    "lorentzian = sm.Lorentzian(display_name='Lorentzian', center=-1.0, width=0.2, area=1.0)\n",
-    "polynomial = sm.Polynomial(display_name='Polynomial', coefficients=[0.1, 0, 0.5])  # y=0.1+0.5*x^2\n",
+    "gaussian = edyn.Gaussian(display_name='Gaussian', width=0.5, area=1)\n",
+    "dho = edyn.DampedHarmonicOscillator(display_name='DHO', center=1.0, width=0.3, area=2.0)\n",
+    "lorentzian = edyn.Lorentzian(display_name='Lorentzian', center=-1.0, width=0.2, area=1.0)\n",
+    "polynomial = edyn.Polynomial(\n",
+    "    display_name='Polynomial', coefficients=[0.1, 0, 0.5]\n",
+    ")  # y=0.1+0.5*x^2\n",
     "\n",
     "# Adding components to the component collection\n",
     "component_collection.append_component(gaussian)\n",

docs/docs/tutorials/components.ipynb

@@ -23,7 +23,7 @@
     "import numpy as np\n",
     "import scipp as sc\n",
     "\n",
-    "import easydynamics.sample_model as sm\n",
+    "import easydynamics as edyn\n",
     "\n",
     "%matplotlib widget"
    ]
@@ -36,13 +36,13 @@
    "outputs": [],
    "source": [
     "# Creating a component\n",
-    "gaussian = sm.Gaussian(display_name='Gaussian', width=0.5, area=1)\n",
-    "dho = sm.DampedHarmonicOscillator(display_name='DHO', center=1.0, width=0.3, area=2.0)\n",
-    "lorentzian = sm.Lorentzian(display_name='Lorentzian', center=-1.0, width=0.2, area=1.0)\n",
-    "polynomial = sm.Polynomial(\n",
+    "gaussian = edyn.Gaussian(display_name='Gaussian', width=0.5, area=1)\n",
+    "dho = edyn.DampedHarmonicOscillator(display_name='DHO', center=1.0, width=0.3, area=2.0)\n",
+    "lorentzian = edyn.Lorentzian(display_name='Lorentzian', center=-1.0, width=0.2, area=1.0)\n",
+    "polynomial = edyn.Polynomial(\n",
     "    display_name='Polynomial', coefficients=[-0.2, 0, 0.5]\n",
     ")  # y=-0.2+0.5*x^2\n",
-    "exponential = sm.Exponential(display_name='Exponential', amplitude=1.0, rate=-0.5)\n",
+    "exponential = edyn.Exponential(display_name='Exponential', amplitude=1.0, rate=-0.5)\n",
     "\n",
     "x = np.linspace(-2, 2, 100)\n",
     "\n",
@@ -94,7 +94,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "delta = sm.DeltaFunction(display_name='Delta', center=0.0, area=1.0)\n",
+    "delta = edyn.DeltaFunction(display_name='Delta', center=0.0, area=1.0)\n",
     "x1 = np.linspace(-2, 2, 100)\n",
     "y = delta.evaluate(x1)\n",
     "x2 = np.linspace(-2, 2, 51)\n",
@@ -122,7 +122,9 @@
     "x1 = sc.linspace(dim='x', start=-2.0, stop=2.0, num=100, unit='meV')\n",
     "x2 = sc.linspace(dim='x', start=-2.0 * 1e3, stop=2.0 * 1e3, num=101, unit='microeV')\n",
     "\n",
-    "polynomial = sm.Polynomial(display_name='Polynomial', coefficients=[0.1, 0, 0.5])  # y=0.1+0.5*x^2\n",
+    "polynomial = edyn.Polynomial(\n",
+    "    display_name='Polynomial', coefficients=[0.1, 0, 0.5]\n",
+    ")  # y=0.1+0.5*x^2\n",
     "y1 = polynomial.evaluate(x1)\n",
     "y2 = polynomial.evaluate(x2)\n",
     "\n",
@@ -148,7 +150,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "expr = sm.ExpressionComponent(\n",
+    "expr = edyn.ExpressionComponent(\n",
     "    'A * exp(-(x - x0)**2 / (2*sigma**2)) +B*sin(2*pi*x/period)',\n",
     "    parameters={'A': 10, 'x0': 0, 'sigma': 1},\n",
     "    parameter_units={\n",
@@ -185,7 +187,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "expr = sm.ExpressionComponent(\n",
+    "expr = edyn.ExpressionComponent(\n",
     "    'A*erf(B*x)',\n",
     ")\n",
     "\n",