diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..b4cc81e --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,84 @@ +# FAQs + +__Running lxm3 launch raises `ValueError("Unable to load Config")`__ + +You should make sure that you have created lxm3 configuration file. + +---- + +__Packaging Error when calling `experiment.package`__ +LXM3 runs `pip install` to install your project (without dependnecies) +into a temporary directory and then packages the project into a zip file. +`Packaging Error` means that calling `pip install` on your project has failed. + +The terminal output should contain the error message when calling `pip` +to package your project. + +One way to debug this is to run `pip install` outside the launcher script +to see if your project can be installed properly with `pip`. + +__lxm3 is unable to find my Python modules__ + +This normally means that your Python project is not packaged properly. + +LXM3 relies on standard Python packaging tools to find your packages +and create a zip archive that will be extracted during runtime and added +the packages to your `PYTHONPATH`. + +Therefore, it's important that you understand how your build system +works and how it finds your packages. If this is the first time you +are packaging your Python project, you may want to learn more about it +from [Python Packaging](https://packaging.python.org/). + +One way to check that your Python packages are packaged properly is to +check the contents of wheel file created from your project. You can do +so by running +```bash +pip wheel --no-deps . +``` +and then check the contents of the wheel file created for example by +running +```bash +unzip -t +``` + +You should be able to see your Python packages in the wheel file, in +installed layout. Also check if _data files (configuration files, +assets)_ are included in the wheel. If that is not the case, you +should consult your build system documentation for how to specify the +packages to be included in your project. + +Here is a list of python build systems and their documentation how to +specify files to be packaged. + +| Backend |Documentation | +|-------------|------------------------------------------------------------------------------------------------------------------------------------------------| +| setuptools | [https://setuptools.pypa.io/en/latest/userguide/package_discovery.html](https://setuptools.pypa.io/en/latest/userguide/package_discovery.html) | +| hatchling | [https://hatch.pypa.io/latest/build/](https://hatch.pypa.io/latest/build/) | +| pdm-backend | [https://backend.pdm-project.org/build_config/](https://setuptools.pypa.io/en/latest/userguide/package_discovery.html) | +| flit-core | [https://flit.pypa.io/en/stable/pyproject_toml.html](https://flit.pypa.io/en/stable/pyproject_toml.html) | + +____ + +__How to check job logs when running on a HPC cluster__ + +When you launch on job on the cluster, the terminal should print out a +path where the job logs are stored. You can ssh into the cluster and +inspect that directory which would contain the job logs. + +---- + +__How to rerun a failed job__ + +Currently, LXM3 does not have native support for rerunning failed +jobs. But since LXM3 generates a job script, you can rerun the job by +`qsub` the job script directly. Note that in the context of array +jobs, you would need to specify the array task id to rerun specific +tasks. + +__Do I need to use absl-py in my project?__ +No, it is not necessary for your project to use `absl-py`. +However, the launcher script uses `absl-py` to parse command line arguments. + +You can use any command line argument parser you like, but just make sure +that you pass the command line arguments properly in your launch script. diff --git a/docs/index.rst b/docs/index.rst index 5184fab..70db866 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -51,6 +51,7 @@ and run the command getting_started configuration + faq tips_and_tricks api diff --git a/pdm.lock b/pdm.lock index 4454f1a..e374cf0 100644 --- a/pdm.lock +++ b/pdm.lock @@ -5,7 +5,7 @@ groups = ["default", "dev"] strategy = ["cross_platform"] lock_version = "4.4" -content_hash = "sha256:701b17cdf3b97dd0e3958cacf760b6621580534b8d7122ed7d32ecc712d08e73" +content_hash = "sha256:bc66406e1a1af9b37596b395269f1bec7a1997914c7d5810deac0dffda97a04c" [[package]] name = "absl-py" @@ -662,6 +662,19 @@ files = [ {file = "Jinja2-3.1.2.tar.gz", hash = "sha256:31351a702a408a9e7595a8fc6150fc3f43bb6bf7e319770cbc0db9df9437e852"}, ] +[[package]] +name = "livereload" +version = "2.6.3" +summary = "Python LiveReload is an awesome tool for web developers" +dependencies = [ + "six", + "tornado; python_version > \"2.7\"", +] +files = [ + {file = "livereload-2.6.3-py2.py3-none-any.whl", hash = "sha256:ad4ac6f53b2d62bb6ce1a5e6e96f1f00976a32348afedcb4b6d68df2a1d346e4"}, + {file = "livereload-2.6.3.tar.gz", hash = "sha256:776f2f865e59fde56490a56bcc6773b6917366bce0c267c60ee8aaf1a0959869"}, +] + [[package]] name = "markdown-it-py" version = "3.0.0" @@ -1137,6 +1150,21 @@ files = [ {file = "sphinx-7.2.6.tar.gz", hash = "sha256:9a5160e1ea90688d5963ba09a2dcd8bdd526620edbb65c328728f1b2228d5ab5"}, ] +[[package]] +name = "sphinx-autobuild" +version = "2021.3.14" +requires_python = ">=3.6" +summary = "Rebuild Sphinx documentation on changes, with live-reload in the browser." +dependencies = [ + "colorama", + "livereload", + "sphinx", +] +files = [ + {file = "sphinx-autobuild-2021.3.14.tar.gz", hash = "sha256:de1ca3b66e271d2b5b5140c35034c89e47f263f2cd5db302c9217065f7443f05"}, + {file = "sphinx_autobuild-2021.3.14-py3-none-any.whl", hash = "sha256:8fe8cbfdb75db04475232f05187c776f46f6e9e04cacf1e49ce81bdac649ccac"}, +] + [[package]] name = "sphinx-nameko-theme" version = "0.0.3" @@ -1243,6 +1271,25 @@ files = [ {file = "tomlkit-0.12.2.tar.gz", hash = "sha256:df32fab589a81f0d7dc525a4267b6d7a64ee99619cbd1eeb0fae32c1dd426977"}, ] +[[package]] +name = "tornado" +version = "6.4" +requires_python = ">= 3.8" +summary = "Tornado is a Python web framework and asynchronous networking library, originally developed at FriendFeed." +files = [ + {file = "tornado-6.4-cp38-abi3-macosx_10_9_universal2.whl", hash = "sha256:02ccefc7d8211e5a7f9e8bc3f9e5b0ad6262ba2fbb683a6443ecc804e5224ce0"}, + {file = "tornado-6.4-cp38-abi3-macosx_10_9_x86_64.whl", hash = "sha256:27787de946a9cffd63ce5814c33f734c627a87072ec7eed71f7fc4417bb16263"}, + {file = "tornado-6.4-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f7894c581ecdcf91666a0912f18ce5e757213999e183ebfc2c3fdbf4d5bd764e"}, + {file = "tornado-6.4-cp38-abi3-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:e43bc2e5370a6a8e413e1e1cd0c91bedc5bd62a74a532371042a18ef19e10579"}, + {file = "tornado-6.4-cp38-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:f0251554cdd50b4b44362f73ad5ba7126fc5b2c2895cc62b14a1c2d7ea32f212"}, + {file = "tornado-6.4-cp38-abi3-musllinux_1_1_aarch64.whl", hash = "sha256:fd03192e287fbd0899dd8f81c6fb9cbbc69194d2074b38f384cb6fa72b80e9c2"}, + {file = "tornado-6.4-cp38-abi3-musllinux_1_1_i686.whl", hash = "sha256:88b84956273fbd73420e6d4b8d5ccbe913c65d31351b4c004ae362eba06e1f78"}, + {file = "tornado-6.4-cp38-abi3-musllinux_1_1_x86_64.whl", hash = "sha256:71ddfc23a0e03ef2df1c1397d859868d158c8276a0603b96cf86892bff58149f"}, + {file = "tornado-6.4-cp38-abi3-win32.whl", hash = "sha256:6f8a6c77900f5ae93d8b4ae1196472d0ccc2775cc1dfdc9e7727889145c45052"}, + {file = "tornado-6.4-cp38-abi3-win_amd64.whl", hash = "sha256:10aeaa8006333433da48dec9fe417877f8bcc21f48dda8d661ae79da357b2a63"}, + {file = "tornado-6.4.tar.gz", hash = "sha256:72291fa6e6bc84e626589f1c29d90a5a6d593ef5ae68052ee2ef000dfd273dee"}, +] + [[package]] name = "typing-extensions" version = "4.8.0" diff --git a/pyproject.toml b/pyproject.toml index 1a2ec0f..6e7245c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -51,16 +51,17 @@ shell = ["IPython"] [tool.pdm.dev-dependencies] dev = [ - "coverage[toml]>=6.5", - "pytest", - "pytest-cov", - "pre-commit", - "fabric", - "Sphinx", - "myst-parser", - "sphinx_nameko_theme", - "black>=23.1.0", - "ruff>=0.0.243", + "coverage[toml]>=6.5", + "pytest", + "pytest-cov", + "pre-commit", + "fabric", + "Sphinx", + "myst-parser", + "sphinx_nameko_theme", + "black>=23.1.0", + "ruff>=0.0.243", + "sphinx-autobuild>=2021.3.14", ] [tool.pdm.version]