feat: add dynamic instance management methods to MapdlPool

[Copilot]

Description

Adds dynamic instance management to MapdlPool for runtime pool size adjustment and instance addition.

New Methods:

• increase(n=1) - Spawns n additional instances (local pools only)
• reduce(n=1) - Removes n instances from pool end (validates ≥1 remains)
• add(mapdl) - Adds existing MAPDL instance to pool

Implementation:

• Leverages existing _spawn_mapdl() and exit() infrastructure
• Automatic port allocation via available_ports()
• Full validation: type checks, value bounds, pool state
• increase() restricted to local pools; remote pools must use add()
• Proper initialization of _n_instances after resolution for type safety
• Runtime checks instead of assertions for security compliance

Example:

from ansys.mapdl.core import MapdlPool, launch_mapdl

pool = MapdlPool(2)
pool.increase(3)     # Now 5 instances
pool.reduce(2)       # Now 3 instances

mapdl = launch_mapdl()
pool.add(mapdl)      # Now 4 instances

# Validation prevents invalid operations
pool_1 = MapdlPool(1)
pool_1.reduce(1)     # ValueError: Cannot reduce to < 1 instance

Tests:
15 test cases covering all methods, edge cases, and error conditions using mocks (no real MAPDL launches).

Test Infrastructure Improvements:

• Modified patch_spawn_mapdl mock to return thread-like objects with .join() method for proper test execution
• Added proper environment variable cleanup (PYMAPDL_START_INSTANCE) in tests to ensure consistent behavior across CI/CD environments

Code Quality:

• ✅ All pre-commit hooks passing (mypy, black, flake8, bandit, etc.)
• ✅ Type-safe implementation with proper mypy compliance
• ✅ Security-compliant (no assert statements in production code)
• ✅ CI/CD tests passing with proper mocking infrastructure

Issue linked

Related to issue requesting add_instance and remove_instance methods.

Checklist

• I have visited and read Develop PyMAPDL.
• I have tested my changes locally
• I have added necessary documentation or updated existing documentation.
• I have followed the PyMAPDL coding style guidelines.
• I have added appropriate unit tests that also ensure the minimal coverage criteria.
• I have reviewed my changes before submitting this pull request.
• I have linked the issue or issues that are solved to the PR if any.
• I have assigned this PR to myself.
• I have marked this PR as draft if it is not ready to be reviewed yet.
• I have made sure that the title of my PR follows Commit naming conventions (e.g. feat: adding new MAPDL command)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>MAPDL Pool</issue_title>
<issue_description>It needs "add_instance" and "remove_instance" methods.</issue_description>

Comments on the Issue (you are @copilot in this section)

@germa89 Thank you @francesco123212 ! @germa89 The new methods should allow to increase or reduce the number of instances.

pool = MapdlPool(1)

pool.increase() # add 1
pool.increase(2) # add 2 new
pool.reduce() # remove one
pool.reduce(2) # reduce two

mapdl = launch_mapdl()
pool.add(mapdl) # add the Mapdl instance to the existing pool.

pool_1 = MapdlPool(1)
pool.decrease(1) # raise an error because pools cannot have 0 instances
pool.decrease(3) # raise an error because pools cannot have negative numbers.

The methods should leverage as much as possible of the existing code, however it is understandable that some refactoring needs to be done.

This refactoring should help unit testing, leveraging mocks and patch to avoid launching new MAPDL instances.
Codecoverage should be about 90%. </comment_new>

• Fixes MAPDL Pool #4317

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[germa89]

@copilot make sure you run precommit before pushing.

[Copilot]

@copilot make sure you run precommit before pushing.

Done! All pre-commit hooks are now passing. Fixed mypy type issues by properly initializing _n_instances and replaced assert statements with runtime checks for bandit compliance. Commit: 7d330f1

[germa89]

@copilot

There are some issues within the CICD:

Start instance.

That test should remove the env var "PYMAPDL_START_INSTANCE" using monkeypatch.

[FAILED] TestMapdlPool.test_increase_multiple - tests/test_pool.py:873: ValueError: Cannot automatically increase pool when 'start_instance' is False. Use the 'add()' method to add existing MAPDL instances instead.
[FAILED] TestMapdlPool.test_increase_default - tests/test_pool.py:847: ValueError: Cannot automatically increase pool when 'start_instance' is False. Use the 'add()' method to add existing MAPDL instances instead.

The dict has no "join" method:

tests/test_pool.py:895: 
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 

self = MAPDL Pool with 0 active instances, n = 3

    def increase(self, n: int = 1) -> None:
        """Add instances to the pool.
    
        Parameters
        ----------
        n : int, optional
            Number of instances to add. Default is 1.
    
        Raises
        ------
        ValueError
            If trying to increase pool when start_instance is False.
    
        Examples
        --------
        >>> pool = MapdlPool(2)
        >>> pool.increase()  # add 1 instance
        >>> pool.increase(2)  # add 2 more instances
        """
        if not isinstance(n, int):
            raise TypeError(
                f"Argument 'n' must be an integer, got {type(n).__name__} instead"
            )
        if n < 1:
            raise ValueError(f"Must add at least 1 instance. Got n={n}")
    
        # Runtime check for pool initialization (also helps mypy)
        if self._n_instances is None:
            raise RuntimeError("Pool must be initialized before calling increase()")
    
        if not self._start_instance:
            raise ValueError(
                "Cannot automatically increase pool when 'start_instance' is False. "
                "Use the 'add()' method to add existing MAPDL instances instead."
            )
    
        LOG.debug("Increasing pool size by {n} instances")
    
        # Determine starting index for new instances
        current_count = self._n_instances
    
        # Extend the instances list with None placeholders
        self._instances.extend([None for _ in range(n)])
    
        # Update the total count
        self._n_instances += n
    
        # Get available ports for new instances
        # Find the highest current port and start from there
        current_ports = [inst._port for inst in self if inst is not None]
        if current_ports:
            starting_port = max(current_ports) + 1
        else:
            starting_port = MAPDL_DEFAULT_PORT
    
        new_ports = available_ports(n, starting_port)
    
        # Spawn new instances
        threads = []
        for i in range(n):
            index = current_count + i
            port = new_ports[i]
            ip = LOCALHOST
    
            thread = self._spawn_mapdl(
                index,
                ip=ip,
                port=port,
                name=self._names(index),
                thread_name=self._names(index),
                start_instance=self._start_instance,
                exec_file=self._exec_file,
            )
            threads.append(thread)
    
        # Wait for all threads to complete
        for thread in threads:
>           thread.join()
            ^^^^^^^^^^^
E           AttributeError: 'dict' object has no attribute 'join'

Fix those issues.

[Copilot]

@copilot

There are some issues within the CICD:
...

Fixed both CI issues in commit d087b60:

1. patch_spawn_mapdl now returns mock thread: Modified to return a MagicMock() with a .join() method instead of a dict, so the thread joining code works correctly.

2. Environment variable cleanup: Added monkeypatch.delenv("PYMAPDL_START_INSTANCE", raising=False) to test_increase_default, test_increase_multiple, test_increase_invalid_type, and test_increase_invalid_value to ensure start_instance=True by default.

[codecov]

Codecov Report

❌ Patch coverage is 92.00000% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.20%. Comparing base (36b4637) to head (c90ca5a).
⚠️ Report is 9 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4407      +/-   ##
==========================================
+ Coverage   91.10%   91.20%   +0.09%     
==========================================
  Files         196      196              
  Lines       16076    16153      +77     
==========================================
+ Hits        14646    14732      +86     
+ Misses       1430     1421       -9     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[germa89]

LGTM

[germa89]

@pyansys-ci-bot LGTM.

[pyansys-ci-bot]

✅ Approving this PR because germa89 said so in here 😬

[Copilot]

Pull request overview

Adds runtime resizing and external instance attachment to MapdlPool, enabling dynamic pool management.

Changes:

• Added MapdlPool.increase(), MapdlPool.reduce(), and MapdlPool.add() APIs for dynamic instance management.
• Updated pool initialization to persist the resolved n_instances value in self._n_instances.
• Added unit tests and strengthened spawn-thread mocking to support .join().

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 7 comments.

File	Description
src/ansys/mapdl/core/pool.py	Implements dynamic pool resize/attach methods and ensures _n_instances is set after resolving args.
tests/test_pool.py	Adds tests for increase/reduce/add and improves spawn mocking to behave like thread objects.
doc/changelog.d/4407.added.md	Documents the new dynamic instance management feature.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

n is not interpolated here (missing f-string / logger formatting arguments), so logs will literally contain {n}. Use an f-string or LOG.debug("Increasing pool size by %d instances", n) for correct logging.

Suggested change

	LOG.debug("Increasing pool size by {n} instances")
	LOG.debug("Increasing pool size by %d instances", n)

[Copilot]

add() bypasses the pool’s unique-port invariant (_verify_unique_ports() is only called in __init__). Adding an instance with a duplicate port can cause incorrect behavior elsewhere (e.g., port-based assumptions, monitoring/restart logic). Add a duplicate-port check before appending (or append then call _verify_unique_ports() and rollback on failure) and raise a clear ValueError if the new instance’s port conflicts.

[Copilot]

add() bypasses the pool’s unique-port invariant (_verify_unique_ports() is only called in __init__). Adding an instance with a duplicate port can cause incorrect behavior elsewhere (e.g., port-based assumptions, monitoring/restart logic). Add a duplicate-port check before appending (or append then call _verify_unique_ports() and rollback on failure) and raise a clear ValueError if the new instance’s port conflicts.

Suggested change

	# Ensure the pool's unique-port invariant is maintained
	try:
	self._verify_unique_ports()
	except Exception as exc: # pragma: no cover - defensive programming
	# Roll back changes if port uniqueness is violated
	self._instances.pop()
	self._n_instances -= 1
	raise ValueError(
	"Cannot add MAPDL instance to pool: duplicate port detected"
	) from exc

[Copilot]

increase() increments _n_instances and extends _instances before spawn completion, and it doesn’t verify the new instances actually became ready after joining. If a spawn fails (or fails silently inside the thread), the pool can be left with None placeholders while _n_instances reports a larger size. Consider deferring _n_instances updates until after successful initialization (and/or performing a readiness check similar to __init__ and raising on failure, rolling back the partially-added entries).

[Copilot]

add() lacks a type annotation for mapdl, even though it enforces MapdlBase at runtime. For better type-safety/mypy support, annotate the parameter (commonly via TYPE_CHECKING + forward reference or a direct import) so callers get correct static typing.

[Copilot]

mock_exit is patched and injected but not used in this test. Either remove the @patch("...MapdlPool.exit") decorator and the mock_exit parameter, or add an assertion reflecting the intended behavior (e.g., mock_exit.assert_not_called() if that’s what you want to validate).

Suggested change

	@patch("ansys.mapdl.core.pool.MapdlPool.exit")
	def test_reduce_default(self, mock_exit, monkeypatch):
	def test_reduce_default(self, monkeypatch):

[Copilot]

launch_mapdl is patched and injected as mock_launch but not used in this test (pool creation is already using the patched _spawn_mapdl, and add() doesn’t call launch_mapdl). Remove this patch/parameter to reduce noise, or assert it is not called if that’s the intent.

Suggested change

	@patch("ansys.mapdl.core.pool.launch_mapdl")
	def test_add_existing_instance(self, mock_launch, monkeypatch):
	def test_add_existing_instance(self, monkeypatch):