doc: add PyScadeOne to official PyAnsys libraries

[ansfcouadau]

As discussed with @jorgepiloto, here is a PR to add our newly-published PyScadeOne library to the official PyAnsys docs.

What I have tested

• ✅ I built the HTML docs locally using doc/make.bat html and confirmed that PyScadeOne tiles appear in the various pages.

What I could not test locally

• ❓ Product family: I used a new product family, "Embedded Software", for PyScadeOne. However, on my local version of the HTML docs, the left menu with product families stays empty, so I could not check that it displays correctly.
• ❓ Possible dependency conflict with PyMechanical: in my early attempts to build the doc, I (mistakenly) ran tox and saw a dependency conflict error (see below). I do not know if this error is problematic or not (Mechanical and Scade One are not really used together). Here's the full trace:

Collecting cffi==1.17.1 (from ansys-scadeone-core==0.6.1)
  Downloading cffi-1.17.1-cp310-cp310-win_amd64.whl.metadata (1.6 kB)
INFO: pip is looking at multiple versions of ansys-scadeone-core to determine which version is compatible with other requirements. This could take a while.

The conflict is caused by:
    ansys-mechanical-core 0.11.12 depends on clr-loader==0.2.7.post0
    ansys-scadeone-core 0.6.1 depends on clr-loader==0.2.6

To fix this you could try to:
1. loosen the range of package versions you've specified
2. remove package versions to allow pip to attempt to solve the dependency conflict

ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/topics/dependency-resolution/#dealing-with-dependency-conflicts
py: exit 1 (34.36 seconds) C:\Users\fcouadau\git\pyansys> python -I -m pip install ansys-acp-core==0.1.0 ansys-additive-core==0.19.1 ansys-additive-widgets==0.2.1 ansys-conceptev-core==0.8 ansys-dpf-composites==0.6.2 ansys-dpf-co==0.8 ansys-dpf-composites==0.6.2 ansys-dpf-core==0.13.4 ansys-dpf-post==0.9.2 ansys-dyna-core==0.7.0 ansys-dynamicreporting-core==0.9.0 ansys-edb-core==0.1.9 ansys-fluent-core==0.28.=0.9.1 ansys-mapdl-core==0.68.6 ansys-math-cor2 ansys-geometry-core==0.8.2 ansys-hps-client==0.9.1 ansys-mapdl-core==0.68.6 ansys-math-core==0.2.2 ansys-mechanical-core==0.11.12 ansys-meshing-prime==0.7.0 ansys-modelcenter-workflgement==1.1.2 ansys-pyensight-core==0.9.8 ansyow==0.1.1 ansys-motorcad-core==0.7.0 ansys-optislang-core==0.9.3 ansys-platform-instancemanagement==1.1.2 ansys-pyensight-core==0.9.8 ansys-rocky-core==0.3.2 ansys-scadeone-core==0.6.turbogrid-core==0.4.1 ansys-workbench-core==0.1 ansys-seascape==0.2.0 ansys-sherlock-core==0.8.2 ansys-simai-core==0.2.6 ansys-sound-core==0.1.3 ansys-systemcoupling-core==0.8.0 ansys-turbogrid-core==0.4.1 ansys-workbench-core==0.7.0 pyaedt==0.13.3 pyedb==0.36.0 pygranta==2025.1.0 pytwin==0.7.0 pid=20524
.pkg: _exit> python C:\Users\fcouadau\AppData\Local\Programs\Python\Python310\lib\site-packages\pyproject_api\_backend.py True flit_core.buildapi
  py: FAIL code 1 (34.77 seconds)
  evaluation failed :( (35.19 seconds)

[ansfcouadau]

It looks like the dependency conflict with PyMechanical is raised by CI/CD.

@jorgepiloto, do you have any advice on how to solve this kind of thing? Do we need to publish an update to PyScadeOne, or are there ways to fix the build in the PyAnsys project?

[RobPasMue]

Hi @ansfcouadau @jorgepiloto ...

I had a look at the PyScadeOne dependencies and I have to raise my concerns about something:

All your dependencies seem to be pinned down to specific versions, which makes it very difficult that your library is compatible with other libraries. Would it be possible to make them more flexible?

[ansfcouadau]

@RobPasMue thanks for the feedback. We haven't tested for conflicting dependencies as part of developing our first version of PyScadeOne.

Would you be able to add @xfornari to the contributors of this repo, so that we can loop him into this discussion?

[greschd]

Hi @ansfcouadau,

To expand on @RobPasMue's comment, let me describe the intended dependency versioning scheme in a bit more detail [1]:

In general, PyAnsys libraries should keep their dependency version ranges open. In your case, that might mean changing the dependencies in pyproject.toml to (for example) [2]

    "Jinja2>=3.1.4",
    "jsonschema>=4.23.0",
    "platformdirs>=4.3.2",
    "pyparsing>=3.1.4",
    "pythonnet>=3.0.4",
    "typing_extensions>=4.12.2",

Only versions which are known not to be compatible should be excluded.

The reason for this is simple: since there is a large number of PyAnsys libraries, coordinating on a specific version of dependencies would be an almost-impossible coordination task. Additionally, users may want to install third-party packages into their Python environment which we do not control.
The way the Python packaging ecosystem works, it's easy for downstream consumers to additionally restrict the set of versions they want to install, but loosening an upstream requirement is not possible (at least with default tooling).

Since version pinning is important for reproducibility of builds, it should be done in the following ways:

• Applications using PyAnsys libraries should fully pin their (direct and transitive) dependencies
• Libraries :
  • Maintain a separate "lockfile" of fully pinned dependencies. This is used only for dev / CICD, not when pip install-ing the package.
  • An automated process (e.g. dependabot) regularly checks for available updates to the lockfile, and creates PRs to update it. This makes any breaking changes in dependencies visible
  • The exact mechanism of how the lockfile is produced / updated / used depends on the build system (setuptools / flit / poetry / ...) used.
• The PyAnsys meta-package ships a fully specified set of dependencies in its release artifacts.

Would you be able to add @xfornari to the contributors of this repo, so that we can loop him into this discussion?

Anyone can comment here! The contributors permission is only needed for pushing new branches / code.

---

[1] I tried finding if this is documented somewhere, but couldn't find it. @RobPasMue did I just miss it, or do we need to add documentation for this?
[2] Notice also that only direct dependencies are listed, not indirect ones.

[RobPasMue]

Thanks a lot for your detailed explanation @greschd! And yeah, we might not have documented this anywhere yet... and assumed it as common knowledge (which we shouldn't). I will put up a backlog issue on the dev guide :)

[xfornari]

Hi there, the problem is the following. Following Ansys rules:

• either pyscadeone is developed under GitHub, and if used within/delivered with a product, it must be considered as an OSS, and 3rd party process applies,

• or it is developed as a standard component/product under ADO, and then all the packages it uses fall into OSS declaration, and implies the "=", as "=>" means the minimum requirements, but no guarantee is offered above

Our management asked for a strict development under ADO to follow the development in the same way as other components of Scade One, with GitHub repo containing snapshots of releases. So the 2nd bullet applies, with OSS declaration.

Nevertheless, we use the https://github.com/ansys/ansys-tools-repo-sync tool which helps copying from private repo to public repo. Then, at some point, the same case exists in Ansys, with a private repository requiring strict OSS process (hence the "=") and a public repository.

One possibility would be to have the product version "guaranteed" ("=") and the github version more open (like X.Y. for ADO and X.Y. for GitHub), or to relax OSS rules for Python ? or found another way with our management team?

I'm for the "<=", but it is currently against the OSS rules.

@RobPasMue, @ansfcouadau : this is beyond the PR, in my opinion.

[greschd]

How is the package consumed for the purposes of the ADO build?

I think it might still be possible to use locked dependencies within the ADO build, and (matching) version ranges for consumption with pip and the PyAnsys ecosystem. [1]

It might be helpful to schedule a direct discussion with @RobPasMue and maybe others to understand the context better.

@RobPasMue, @ansfcouadau : this is beyond the PR, in my opinion.

Unfortunately the current pinned dependencies are incompatible with the PyAnsys metapackage (both specifically, and in principle), so it blocks merging the PR from my point of view.

It might still be okay to put it onto the documentation without including it in the pyansys package itself, but this just means it will be difficult / impossible to install alongside other PyAnsys packages in the same Python environment.

---

[1] The PyAnsys packaging / versioning scheme also aligns with how we are evolving the internal build / versioning process. For details, we should discuss in a non-public location.

[ansfcouadau]

Thank you all for the detailed answers.

I concur that an internal discussion would be best as a next step. I will send an invite.

@greschd: in the meantime, I would be in favor of adding PyScadeOne to the docs without including it to the pyansys package, as you suggested. While this is not ideal, ansys-mechanical-core is the only package that has a dependency conflict with ansys-scadeone-core as of now, and both products are rarely used together.
Would you agree with this as a temporary approach? If so, how should we proceeed? Do I simply roll back my changes to pyproject.toml?

[RobPasMue]

Thank you all for the detailed answers.

I concur that an internal discussion would be best as a next step. I will send an invite.

@greschd: in the meantime, I would be in favor of adding PyScadeOne to the docs without including it to the pyansys package, as you suggested. While this is not ideal, ansys-mechanical-core is the only package that has a dependency conflict with ansys-scadeone-core as of now, and both products are rarely used together. Would you agree with this as a temporary approach? If so, how should we proceeed? Do I simply roll back my changes to pyproject.toml?

Let's hold off until the discussion @ansfcouadau -- I haven't tested it but I'm pretty sure ansys-mechanical-core won't be the only one complaining in the longer run (if there are not more packages complaining about other dependencies already). Dependency resolution issues are not seen all at once with this CI/CD approach - you will only see the first dependency blocking from installing it.

[RobPasMue]

We can add it only to the docs if desired -- just remove it from the pyproject.toml if possible

[xfornari]

I would suggest to let the PR open for now. The better solution would be to update our dependencies with "=>" and have a new release. Then an update of the current branch would resolve everything for the PR. but let us check first with rest of the team if they agree. We go back soon. (and let's have the meeting separately for the future releases)

[ansfcouadau]

Short update:

• We have decided a path forward today to solve the metapackage dependency issues in PyScadeOne. We will implement this as part of releasing version 2025 R2.
• I will confirm, end of this week, what we want to do with this pull request: either push just the docs for now, or retract this PR and await the next version.

Thank you all! Stay tuned.

[ansfcouadau]

Hello all,

As confirmed internally, we are only integrating the PyScadeOne docs to this Pull Request. On the next release of PyScadeOne, (with solved dependency issues), we will propose a new Pull Request to integrate the library to the PyAnsys metapackage.

Thank you all for your support.

[RobPasMue]

Sounds good! Thanks @ansfcouadau